Error Handling

Error responses and codes.

Error Response Format

{
  "error": "error_code",
  "message": "Human-readable error description",
  "details": {},
  "status": "error"
}

Common Error Codes

Authentication Errors

Code	HTTP Status	Description
authentication_required	401	Missing authentication
invalid_api_key	401	Invalid or expired API key
invalid_token	401	Invalid or expired JWT
insufficient_permissions	403	Missing required permissions

Validation Errors

Code	HTTP Status	Description
validation_error	400	Request validation failed
invalid_model	400	Model not found or unavailable
invalid_provider	400	Provider not supported
missing_required_field	400	Required field missing

Resource Errors

Code	HTTP Status	Description
not_found	404	Resource not found
agent_not_found	404	Agent does not exist
tenant_not_found	404	Tenant does not exist

Rate Limiting

Code	HTTP Status	Description
rate_limit_exceeded	429	Too many requests
quota_exceeded	429	Monthly quota exceeded

Provider Errors

Code	HTTP Status	Description
provider_error	502	Upstream provider error
provider_timeout	504	Provider request timeout
provider_unavailable	503	Provider temporarily unavailable

Server Errors

Code	HTTP Status	Description
internal_error	500	Unexpected server error
service_unavailable	503	Service maintenance

Error Examples

Invalid API Key

{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid or expired",
  "status": "error"
}

Rate Limit Exceeded

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 60 seconds.",
  "details": {
    "limit": 100,
    "remaining": 0,
    "reset": 1702837200
  },
  "status": "error"
}

Validation Error

{
  "error": "validation_error",
  "message": "Request validation failed",
  "details": {
    "field": "query",
    "issue": "Query cannot be empty"
  },
  "status": "error"
}

Provider Error

{
  "error": "provider_error",
  "message": "OpenAI API returned an error",
  "details": {
    "provider": "openai",
    "original_error": "Rate limit exceeded"
  },
  "status": "error"
}

GET /api/errors

List recent errors.

Authentication: Not required

Response:

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "error": "provider_error",
      "message": "OpenAI API error",
      "timestamp": "2025-12-17T18:00:00.000Z"
    }
  ],
  "count": 10
}

GET /api/errors/metrics

Error metrics and statistics.

Authentication: Not required

Response:

{
  "success": true,
  "total_errors": 50,
  "by_type": {
    "provider_error": 30,
    "rate_limit_exceeded": 15,
    "validation_error": 5
  },
  "error_rate": 0.05
}