Vision AI Agents — Error Handling

Vision AI Agents APIs return standardized HTTP response codes and structured error messages to help developers quickly diagnose and resolve issues.

When a request fails, the API returns an HTTP status code along with a JSON response describing the error.

Error Response Format

All API errors follow a consistent JSON structure.

Example error response:

{
  "error": "invalid_request",
  "message": "Missing required parameter: video_id"
}

Error Response Fields

Field	Type	Description	Example
error	string	Machine-readable error code used for programmatic handling	invalid_request
message	string	Human-readable description of the error	Missing required parameter: video_id

Developers should use the error code to implement automated error handling logic.

HTTP Status Codes

Vision AI Agents uses standard HTTP response codes.

Status Code	Name	Description
200	Success	Request completed successfully
400	Bad Request	Invalid request parameters or malformed JSON
401	Unauthorized	Missing or invalid API key
404	Not Found	Requested resource could not be located
429	Rate Limit Exceeded	Request exceeds usage tier limits
500	Internal Server Error	Unexpected platform error

Common Error Codes

Error Code	HTTP Status	Description	Retry Recommended
invalid_request	400	Request is missing required parameters or contains invalid data	No
unauthorized	401	Request does not include a valid API key	No
not_found	404	The requested resource (such as video_id) does not exist	No
rate_limit_exceeded	429	Developer has exceeded concurrency or request limits	Yes
internal_error	500	Unexpected error occurred within the platform	Yes

Error Examples

Invalid Request

Occurs when the request body is malformed or required parameters are missing.

{
  "error": "invalid_request",
  "message": "Missing required parameter: video_id"
}

To resolve this error, verify that all required request parameters are included.

Unauthorized

Occurs when the request is missing a valid API key.

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

Ensure the request header includes:

Authorization: Bearer YOUR_API_KEY

Resource Not Found

Occurs when the requested resource does not exist.

{
  "error": "not_found",
  "message": "Video ID not found"
}

Verify that the video_id exists and was successfully ingested.

Rate Limit Exceeded

Occurs when API usage exceeds the limits defined by the developer's usage tier.

{
  "error": "rate_limit_exceeded",
  "message": "API rate limit exceeded for current usage tier"
}

Developers should implement retry logic or upgrade their usage tier.

Internal Server Error

Indicates an unexpected platform issue.

{
  "error": "internal_error",
  "message": "Unexpected server error"
}

Retry the request after a short delay.

If the error persists, contact support.

Retry Strategy

Developers should implement retry logic for temporary failures.

Typical retryable errors include:

rate limit responses
internal server errors
temporary processing delays

Recommended retry strategy:

Wait a short delay (1–3 seconds)
Retry the request
Use exponential backoff for repeated failures

Example retry pattern:

1s → 2s → 4s → 8s

This prevents excessive request traffic while allowing recovery from temporary failures.

Debugging Failed Requests

When debugging API errors, developers should verify the following.

Check	Description
Authorization Header	Ensure the API key is included and valid
Request JSON	Verify request structure and formatting
Required Parameters	Confirm required fields such as video_id are present
Video ID	Verify the referenced video exists and was ingested successfully
Rate Limits	Ensure the request does not exceed concurrency or daily limits

Logging both the request payload and the API response will significantly accelerate troubleshooting.

Support

If errors persist or unexpected responses occur, contact Vision AI Agents support.

Support contact:

support@roboticaxai.com

When reporting issues, include the following information.

Information Required	Description
API Endpoint	The endpoint used in the request
Request Payload	The JSON body sent to the API
Response Received	The full response returned by the API
Timestamp	Time the request occurred

Providing this information allows support engineers to diagnose issues quickly.