Error Handling

The Opally API uses standard HTTP status codes and returns consistent error objects.

Error Response Format

All error responses follow this structure:

{
  "error": "Human-readable error message"
}

For validation errors with additional context:

{
  "error": "Bad Request",
  "details": "guest_message must be a non-empty string"
}

HTTP Status Codes

Status Code	Meaning
200	Success — request completed successfully
400	Bad Request — invalid parameters or request body
401	Unauthorized — missing or invalid API key
403	Forbidden — API key is inactive or lacks permission
404	Not Found — the requested resource doesn't exist
500	Internal Server Error — something went wrong on our side

Common Errors

Authentication Errors (401)

# Missing Authorization header
HTTP 401
{ "error": "Missing API key" }

# Invalid, not found, or revoked key
HTTP 401
{ "error": "Invalid API key" }

Validation Errors (400)

# Invalid date format
HTTP 400
{ "error": "Invalid 'from' date format. Use ISO 8601 (e.g. 2026-01-01)" }

# Invalid query parameter
HTTP 400
{ "error": "Invalid status filter" }

Not Found Errors (404)

# Resource not found or doesn't belong to your company
HTTP 404
{ "error": "Chat conversation not found" }

Rate Limiting

The Opally API is rate-limited at the infrastructure level. If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait a few seconds before retrying.

Best Practices

• Check the status code first before parsing the response body

• Handle 401/403 errors by verifying your API key is valid and active

• Implement retry logic with exponential backoff for 429 and 5xx errors

• Log error responses for debugging — they contain helpful messages