Error Handling

Our API uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

Status Code	Description
200 - OK	The request was successful
201 - Created	The resource was successfully created
400 - Bad Request	The request was invalid or cannot be served
401 - Unauthorized	Authentication credentials are missing or invalid
403 - Forbidden	The authenticated user doesn't have permission to access the requested resource
404 - Not Found	The requested resource doesn't exist
409 - Conflict	The request conflicts with the current state of the server
422 - Unprocessable Entity	The request was well-formed but was unable to be followed due to semantic errors
429 - Too Many Requests	Too many requests hit the API too quickly
500, 502, 503, 504 - Server Errors	Something went wrong on our end

Error Response Format

All error responses include a JSON object with the following properties:

{
  "error": "error_code",
  "message": "A human-readable message providing more details about the error",
  "details": {
    // Additional information about the error (optional)
  }
}

Common Error Codes

Error Code	Description
invalid_request	The request was malformed or missing required parameters
unauthorized	Authentication failed
forbidden	The authenticated user doesn't have the necessary permissions
not_found	The requested resource doesn't exist
rate_limited	Too many requests in a given amount of time
server_error	An error occurred on our servers

Examples

Invalid Request

{
  "error": "invalid_request",
  "message": "Missing required parameter: project_id",
  "details": {
    "parameter": "project_id"
  }
}

Authentication Error

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

Permission Error

{
  "error": "forbidden",
  "message": "API key does not have documents:write scope",
  "details": {
    "required_scope": "documents:write"
  }
}

Handling Errors

When building integrations with our API, we recommend:

1. Always check the HTTP status code of the response
2. Parse the error message and code for more details
3. Implement appropriate retry logic for server errors (5xx) and rate limiting (429)
4. Log detailed error information for debugging

Rate Limiting

Our API implements rate limiting to protect against abuse. If you exceed the rate limit, you'll receive a 429 Too Many Requests response with headers indicating when you can retry:

Retry-After: 30

This header indicates the number of seconds to wait before retrying the request.