Errors

Error codes and response format for the Messaging API.

v1

The Messaging API uses standard HTTP status codes and returns consistent error objects across all endpoints.

Error Response Format

Authentication Error (401)

Returned when the x-network-api-key header is missing or invalid.

{
  "detail": "Not authenticated"
}

Validation Error (422)

Returned when required fields are missing or request parameters are invalid.

{
  "detail": [
    {
      "loc": ["body", "task_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

detail · array

List of validation error objects.

Show validation error properties

loc · array

Path to the field that failed validation (e.g., ["body", "task_id"]).

msg · string

Human-readable error message.

type · string

Machine-readable error type.

Application Error (400)

Returned for application-level errors such as content moderation. May include dynamic extra_data with contextual information.

{
  "status_code": 400,
  "description": "Content moderation triggered",
  "message": "The message was flagged by content moderation.",
  "extra_data": {
    "moderation_category": "harmful_content",
    "flagged_text": "..."
  }
}

status_code · integer

HTTP status code.

description · string

Short error description.

message · string

Detailed error message.

extra_data · object

Dynamic contextual data specific to the error. Structure varies by error type.

Server Error (5xx)

Returned for internal server errors. The response follows the same format as application errors:

{
  "status_code": 500,
  "description": "Internal server error",
  "message": "An unexpected error occurred.",
  "extra_data": {}
}

Error Codes

Status	Description
400	Application error — may include extra_data with moderation or processing details
401	Missing or invalid x-network-api-key header
422	Validation error — invalid or missing request parameters
500	Internal server error

WebSocket Errors

WebSocket connections use close codes instead of HTTP status codes:

Close Code	Meaning
1008	Authentication failure or policy violation
1011	Internal server error

See the WebSocket documentation for details on error handling in streaming connections.

Handling Errors

Node.js

const response = await fetch(
  "https://data-services.aui.io/api/ia-controller/api/v1/external/message",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-network-api-key": "your-api-key",
    },
    body: JSON.stringify({
      task_id: "68e78d0dc5a4b19a030d03d6",
      text: "Hello",
    }),
  }
);

if (!response.ok) {
  const error = await response.json();

  if (response.status === 401) {
    console.error("Authentication failed:", error.detail);
  } else if (response.status === 422) {
    error.detail.forEach((err) => {
      console.error(`Validation: ${err.loc.join(".")} — ${err.msg}`);
    });
  } else {
    console.error(`Error ${error.status_code}: ${error.message}`);
  }
}