Understanding error responses

All error responses follow a consistent JSON format with descriptive HTTP status codes. For backward compatibility, the error field is always present. Newer responses may also include additional structured fields for programmatic handling.

Standard error response format

{
  "error": "Customer-facing error message",
  "code": "MACHINE_READABLE_ERROR_CODE",
  "message": "Internal error details (optional)",
  "details": {
    "key": "Additional context (optional)"
  },
  "invalid_args": [
    {
      "field": "field_name",
      "tag": "Validation error details"
    }
  ]
}

Field descriptions

Field	Type	Required	Description
`error`	String	Required	Human-readable, customer-facing message (always present).
`code`	String	Required	Machine-readable error code for application logic.
`message`	String	Optional	Optional internal/debug detail.
`details`	Object	Optional	Optional structured context.
`invalid_args`	Array of Objects	Optional	Field-level validation errors (used with `400` responses).

Quick reference

Status Code	Error Type	When It Occurs	Recommended Action
`400`	Bad Request	Invalid parameters or request format	Check your request payload and parameters
`401`	Unauthorized	Missing or invalid API key	Verify your API key is correct and active
`403`	Forbidden	IP restrictions or insufficient permissions	Check IP allowlist and API key permissions
`404`	Not Found	Invalid endpoint or resource ID	Verify the endpoint URL and resource exists
`415`	Unsupported Media	Invalid `Content-Type` header	Use `application/json`
`422`	Unprocessable Entity	Valid format but invalid data	Check data values against API requirements
`429`	Rate Limited	Too many requests	Implement retry logic with backoff
`500`	Internal Server Error	Server-side issue	Retry the request; contact support if persistent
`502`	Bad Gateway	Upstream service error	Temporary issue; retry after a brief delay

Detailed error types

`400 Bad Request`

What it means: Your request has invalid syntax, missing required fields, or incorrect parameter values.

Common scenarios:

When you specify tags that don't exist in your workflow configuration:

{
  "error": "tags not present: Green2. Valid tags are: Approve, Blue, Decline, Fraud, Green, Review, Yellow",
  "code": "INVALID_REQUEST"
}

Solution: Use only the tags listed in the error message.

Additional `400` scenarios

Workflow not found or invalid version

{
  "error": "workflow not found with the given version",
  "code": "WORKFLOW_NOT_FOUND"
}

Workflow exists but is not published

{
  "error": "workflow is not published",
  "code": "WORKFLOW_NOT_PUBLISHED"
}

Malformed JSON in request body

{
  "error": "The evaluation request body contains invalid JSON. Please ensure your request is properly formatted JSON.",
  "code": "INVALID_PAYLOAD"
}

Invalid or empty ID field

{
  "error": "specified id is invalid",
  "code": "INVALID_ID"
}

Troubleshooting steps:

Validate your request payload against the API specification.
Ensure all required fields are included.
Check that field values match the expected format and constraints.
Verify file attachments use supported formats.

`401 Unauthorized`

What it means: Your request lacks valid authentication credentials, or your identity does not have required permissions.

Common causes:

Missing API key/bearer token in the request header.
Invalid or expired API key/token.
Token is valid, but RBAC permissions are insufficient for the requested workflow or action.

{
  "error": "authentication failed",
  "code": "AUTHENTICATION_FAILED"
}

{
  "error": "you don't have permission to access this workflow",
  "code": "PERMISSION_DENIED"
}

Troubleshooting steps:

Ensure your API key is included in the request header: Authorization: Bearer YOUR_API_KEY
Verify your API key is active in your account settings.
Check for any typos in the API key/token.
Confirm the token has permissions for the workflow or endpoint being accessed.
If the key/token was recently regenerated, update it in your application.

`403 Forbidden`

What it means: Your request is authenticated but blocked by security policy.

Common causes:

IP address not on the allowlist.
IP filtering enabled but no rules configured.

{
  "error": "ip address rejected",
  "code": "IP_NOT_ALLOWED"
}

{
  "error": "ip address rejected, no filter configured",
  "code": "NO_IP_FILTER_CONFIGURED"
}

Troubleshooting steps:

Verify your IP address is allowlisted in your account settings.
If IP filtering is enabled, confirm at least one rule is configured.
If the issue persists, contact support with the error code and request details.

`404 Not Found`

What it means: The requested resource or endpoint doesn't exist.

Common causes:

Incorrect endpoint URL.
Invalid resource ID (e.g., evaluation_id).
Typo in the API path.

{
  "error": "evaluation record not found"
}

Troubleshooting steps:

Double-check the endpoint URL against the API documentation.
Verify the resource ID exists and belongs to your account.
Ensure you're using the correct HTTP method (GET, POST, etc.).

`415 Unsupported Media Type`

What it means: The request Content-Type is not supported (for example, sending text/plain instead of JSON).

{
  "error": "unsupported media type: text/plain path: /v1/evaluation only accepts Content-Type application/json",
  "code": "UNSUPPORTED_MEDIA_TYPE"
}

Troubleshooting steps:

Set Content-Type: application/json.
Ensure the request body is valid JSON.

`422 Unprocessable Entity`

What it means: Your request is well-formed but contains semantic errors or unsupported data values.

{
  "error": "unsupported_schema",
  "message": "Address country not supported"
}

Troubleshooting steps:

Check that all data values conform to the expected schema.
Verify country codes, currencies, and other standardized fields.
Ensure data relationships are valid (e.g., valid workflow for your account).

`429 Too Many Requests`

What it means: You've exceeded your API rate limit.

{
  "error": "rate_limit",
  "message": "Too many requests, slow down"
}

Troubleshooting steps:

Immediate response: Wait for the time specified in the Retry-After header.
Long-term solution: Implement exponential backoff in your retry logic.
Prevention: Distribute requests evenly over time rather than in bursts.

`500 Internal Server Error`

What it means: An unexpected error occurred on our servers.

{
  "error": "workflow test execution failed",
  "code": "INTERNAL_ERROR"
}

Troubleshooting steps:

Retry the request after a short delay.
If the error persists, check our status page for known issues.
Contact support with the request details and error code.

`502 Bad Gateway`

What it means: Our API gateway received an invalid response from an upstream service.

Troubleshooting steps:

This is typically a temporary issue - retry after a brief delay.
If the problem continues, check our status page.
Contact support if the issue affects critical operations.

Best practices for error handling

Use Error Codes

Use the code field for programmatic handling instead of parsing error strings.

Implement Retry Logic

Always implement retry logic for temporary errors (429, 500, 502) with exponential backoff to avoid overwhelming the service.

Log Error Details

Log the full error response (especially code, message, and details), request details, and timestamp to help with debugging and support requests.

Handle Gracefully

Provide meaningful error messages to your users instead of exposing raw API errors.