Error Reference

Complete reference for error codes and handling in the Zazmic Agents API.

Error Response Format

All API errors follow a consistent JSON structure:

{
  "error": "Error Type",
  "message": "Detailed human-readable error message",
  "statusCode": 400,
  "details": {
    "field": "Additional context"
  }
}

HTTP Status Codes

400 Bad Request

Invalid request format or parameters.

{
  "error": "Bad Request",
  "message": "Missing required field: endpointId",
  "statusCode": 400
}

Common Causes:

• Missing required fields
• Invalid parameter types
• Malformed JSON
• Invalid parameter values

How to Fix:

• Validate request body against endpoint schema
• Ensure all required fields are present
• Check parameter types match expected values

401 Unauthorized

Missing or invalid authentication.

{
  "error": "Unauthorized",
  "message": "No authorization header provided",
  "statusCode": 401
}

Common Causes:

• Missing Authorization header
• Invalid API key format
• Expired or revoked API key
• No active session (for session auth)

How to Fix:

• Include Authorization: Bearer YOUR_API_KEY header
• Generate new API key if expired
• Verify API key is correct

403 Forbidden

Valid authentication but insufficient permissions or balance.

{
  "error": "Insufficient balance",
  "message": "Your balance ($5.00) is insufficient for this task ($10.00). Please add credits.",
  "statusCode": 403
}

Common Causes:

• Insufficient account balance
• User does not have access to agent
• Account suspended or restricted

How to Fix:

• Add credits to account
• Contact support for access issues
• Check account status

404 Not Found

Resource does not exist.

{
  "error": "Not Found",
  "message": "Agent endpoint not found",
  "statusCode": 404
}

Common Causes:

• Invalid agent/endpoint/session/task ID
• Resource was deleted
• Typo in URL path

How to Fix:

• Verify resource ID is correct
• Check if resource still exists
• Use LIST endpoints to find valid IDs

429 Too Many Requests

Rate limit exceeded.

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit of 10 requests per minute",
  "statusCode": 429,
  "details": {
    "retryAfter": 45
  }
}

Rate Limits:

• 10 agent executions per minute per user
• Automatic blocking after 10 failed tasks in 10 minutes

How to Fix:

• Implement exponential backoff
• Use retryAfter value from response
• Distribute requests over time
• Consider upgrading plan for higher limits

Response Headers:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642252800
Retry-After: 45

500 Internal Server Error

Server-side error.

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred. Please try again.",
  "statusCode": 500
}

How to Fix:

• Retry request with exponential backoff
• Check status page  for incidents
• Contact support if persists

503 Service Unavailable

Service temporarily unavailable.

{
  "error": "Service Unavailable",
  "message": "Service is temporarily unavailable. Please try again later.",
  "statusCode": 503
}

How to Fix:

• Retry with exponential backoff
• Check status page for maintenance windows

Task Execution Errors

Errors that occur during agent execution are returned in the task object:

{
  "id": "task_abc123",
  "status": "failed",
  "error": {
    "code": "AGENT_ERROR",
    "message": "Agent execution failed: Connection timeout",
    "details": {
      "timeout": 30000,
      "attemptedAt": "2024-01-15T10:30:00.000Z"
    }
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "completedAt": "2024-01-15T10:30:30.000Z"
}

Error Codes

Chat Stream Errors

Errors during chat streaming:

{
  "type": "error",
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance to complete this request"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Chat Error Codes

Need Help?

• Check the Quickstart Guide for getting started
• Review Authentication setup
• Browse API Reference for endpoint details
• Contact support for persistent errors

Next Steps

• Learn about Tasks API
• Explore Chat streaming
• Understand Rate limiting