Error Codes

The Chatsby API uses conventional HTTP status codes to indicate whether a request succeeded or failed. Every error response follows a consistent JSON format so your application can handle failures programmatically.

Error Response Format

All error responses return a JSON body with a top-level error object:

{
  "error": {
    "type": "invalid_request_error",
    "message": "The 'agent_id' field is required.",
    "code": "missing_required_field",
    "param": "agent_id",
    "status": 400
  }
}

Error Object Fields

Error Types

HTTP Status Code Reference

400 Bad Request

The request is malformed or missing required information.

Common causes:

• Missing a required field (e.g., agent_id, message, name)
• Invalid JSON in the request body
• Parameter value out of allowed range (e.g., temperature > 2.0)
• Malformed URL in a website source

How to fix: Check the param field in the error response to identify which field caused the issue. Review the endpoint's parameter documentation.

{
  "error": {
    "type": "invalid_request_error",
    "message": "The 'name' field is required when creating an agent.",
    "code": "missing_required_field",
    "param": "name",
    "status": 400
  }
}

401 Unauthorized

The request lacks valid authentication credentials.

Common causes:

• No Authorization header provided
• Missing the Bearer prefix in the header
• API key is invalid, revoked, or expired
• Using a test key against production endpoints (or vice versa)

How to fix: Ensure your request includes Authorization: Bearer YOUR_API_KEY with a valid key from your dashboard.

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided. Check that your key is correct and has not been revoked.",
    "code": "invalid_api_key",
    "status": 401
  }
}

403 Forbidden

The API key is valid but does not have permission for the requested action.

Common causes:

• The API key's scoped permissions do not include the required scope (e.g., trying to create an agent with a key that only has agents:read)
• Attempting to access a resource that belongs to a different account

How to fix: Check the key's permissions in the dashboard. If the key needs additional scopes, create a new key or update the existing one.

{
  "error": {
    "type": "forbidden_error",
    "message": "This API key does not have the 'agents:write' permission required for this action.",
    "code": "insufficient_permissions",
    "status": 403
  }
}

404 Not Found

The requested resource does not exist.

Common causes:

• The resource ID is incorrect or has a typo
• The resource has been deleted
• The resource belongs to a different account

How to fix: Verify the resource ID. Use the relevant list endpoint to confirm the resource exists.

{
  "error": {
    "type": "not_found_error",
    "message": "No agent found with ID 'agent_nonexistent'.",
    "code": "resource_not_found",
    "param": "agent_id",
    "status": 404
  }
}

409 Conflict

The request conflicts with the current state of a resource.

Common causes:

• Attempting to refresh a source that is already being processed
• Sending a message to a conversation that references a different agent than the one specified
• Creating a resource with a duplicate idempotency key but different parameters

How to fix: Check the current state of the resource and retry when the conflict condition has been resolved.

{
  "error": {
    "type": "conflict_error",
    "message": "Source 'src_abc123defg' is currently being processed. Wait for processing to complete before requesting a refresh.",
    "code": "resource_busy",
    "status": 409
  }
}

422 Unprocessable Entity

The request body is well-formed JSON but fails validation rules.

Common causes:

• String field exceeds maximum length (e.g., system_prompt > 4,000 characters)
• Metadata object has more than 20 keys
• Q&A source content is not valid JSON
• File upload exceeds the 10 MB limit
• Value is the wrong type (e.g., string where a number is expected)

How to fix: Review the validation constraints for the endpoint. The param field identifies the offending field, and the message explains the specific rule that was violated.

{
  "error": {
    "type": "validation_error",
    "message": "The 'system_prompt' field must not exceed 4,000 characters. Received 4,523 characters.",
    "code": "field_too_long",
    "param": "system_prompt",
    "status": 422
  }
}

Field-Level Validation Errors

When multiple fields fail validation, the response may include an errors array with details for each field:

{
  "error": {
    "type": "validation_error",
    "message": "Multiple validation errors occurred.",
    "code": "validation_failed",
    "status": 422,
    "errors": [
      {
        "param": "temperature",
        "message": "Must be between 0.0 and 2.0. Received 3.5.",
        "code": "out_of_range"
      },
      {
        "param": "max_tokens",
        "message": "Must be a positive integer. Received -100.",
        "code": "invalid_value"
      }
    ]
  }
}

429 Too Many Requests

You have exceeded the API rate limit for your key or plan.

Common causes:

• Sending more than the allowed number of requests per minute
• Burst of requests from a loop without throttling
• Multiple services sharing the same API key without coordination

How to fix: Implement exponential backoff. Check the Retry-After header for the number of seconds to wait before retrying.

{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded. Please retry after 12 seconds.",
    "code": "rate_limit_exceeded",
    "status": 429
  }
}

Rate limit headers included in the response:

Recommended retry strategy with exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
 
    if (response.status !== 429) {
      return response;
    }
 
    const retryAfter = response.headers.get('Retry-After');
    const delay = retryAfter
      ? parseInt(retryAfter, 10) * 1000
      : Math.min(1000 * Math.pow(2, attempt), 30000); // Exponential backoff, max 30s
 
    console.warn(`Rate limited. Retrying in ${delay / 1000}s...`);
    await new Promise(resolve => setTimeout(resolve, delay));
  }
 
  throw new Error('Max retries exceeded');
}

500 Internal Server Error

An unexpected error occurred on the Chatsby server.

Common causes:

• Temporary infrastructure issue
• Bug in the Chatsby backend

How to fix: Retry the request after a short delay. If the error persists, contact support with the request_id from the response headers.

{
  "error": {
    "type": "server_error",
    "message": "An internal error occurred. Please try again later. If the problem persists, contact support with request ID: req_abc123.",
    "code": "internal_error",
    "status": 500
  }
}

503 Service Unavailable

The Chatsby API is temporarily unavailable, usually due to planned maintenance or high load.

Common causes:

• Scheduled maintenance window
• Temporary capacity constraints

How to fix: Wait and retry. Check status.chatsby.co for platform status and maintenance schedules.

{
  "error": {
    "type": "server_error",
    "message": "The service is temporarily unavailable. Please try again in a few minutes.",
    "code": "service_unavailable",
    "status": 503
  }
}

Error Codes Summary Table