Skip to main content

​
Error Reference

The Agentix API uses standard HTTP status codes and returns errors in a consistent JSON format.

​
Error Response Format

All error responses follow this structure: 
{
  "error": "A human-readable error message"
}
Validation errors include additional detail: 
{
  "error": "Validation failed",
  "details": [
    {
      "path": "email",
      "message": "Invalid email address"
    },
    {
      "path": "name",
      "message": "String must contain at least 1 character(s)"
    }
  ]
}

​
HTTP Status Codes

​
Success Codes

CodeMeaningWhen
200OKRequest succeeded (GET, PATCH, PUT, DELETE)
201CreatedResource created successfully (POST)

​
Client Error Codes

CodeMeaningCommon Causes
400Bad RequestMalformed JSON, missing required fields, invalid field values
401UnauthorizedMissing or expired session cookie, missing x-tenant-id header
403ForbiddenUser lacks permission (e.g., Agent role trying to publish a workflow)
404Not FoundResource does not exist or belongs to a different workspace
409ConflictDuplicate resource (e.g., creating a contact with an existing phone number, creating a tag with an existing name)
422Unprocessable EntityRequest is well-formed but semantically invalid (e.g., publishing a workflow with validation errors)
429Too Many RequestsRate limit exceeded — see Rate Limiting

​
Server Error Codes

CodeMeaningWhat to Do
500Internal Server ErrorUnexpected server failure. Retry after a brief delay. If persistent, contact support.

​
Common Error Scenarios

​
Authentication Errors (401)

{"error": "Unauthorized"}
Fix: Sign in again to get a fresh session cookie. Ensure you include the x-tenant-id header on every request.

​
Permission Errors (403)

{"error": "Forbidden"}
Fix: Check your user role. Agent-role users cannot publish workflows, manage tools, or modify WhatsApp settings. Ask an Admin to perform the action or upgrade your role.

​
Validation Errors (400 / 422)

{
  "error": "Validation failed",
  "details": [
    {"path": "name", "message": "Required"}
  ]
}
Fix: Check the details array for specific field errors. Correct the request body and retry.

​
Conflict Errors (409)

{"error": "Contact with this phone number already exists"}
Fix: The resource you are trying to create conflicts with an existing one. Use a GET request to find the existing resource, or use a PATCH/PUT to update it instead.

​
Rate Limit Errors (429)

{"error": "Too many requests, please try again later"}
Fix: Wait for the duration specified in the Retry-After response header before retrying. See Rate Limiting for details on limits per endpoint.

​
Workflow Validation Errors (422)

When publishing a workflow, the platform validates the graph structure: 
{
  "error": "Workflow validation failed: no reachable handoff node"
}
Fix: Open the workflow in the visual builder and fix the reported issue. Every published workflow must have at least one reachable Handoff node.

​
Error Handling Best Practices

  1. Always check the status code before parsing the response body
  2. Parse the error field for a human-readable description
  3. Check details on 400/422 responses for field-level validation errors
  4. Implement retry with backoff for 429 and 500 responses
  5. Log the full response for debugging — include status code, headers, and body