v1
The Messaging API uses standard HTTP status codes and returns consistent error objects across all endpoints.
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"
}
]
}
List of validation error objects.Show validation error properties
Path to the field that failed validation (e.g., ["body", "task_id"]).
Human-readable error message.
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": "..."
}
}
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 |
Handling Errors
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}`);
}
}
