Errors

All AEGIS API errors return a consistent JSON structure.

Error Response Format


{
  "detail": "Human-readable error description"
}

For validation errors (422), FastAPI returns a more detailed format:


{
  "detail": [
    {
      "loc": ["body", "field_name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

HTTP Status Codes

Code	Meaning	When It Occurs
`200`	OK	Successful request
`201`	Created	Resource successfully created
`204`	No Content	Successful deletion
`400`	Bad Request	Malformed request body or invalid parameters
`401`	Unauthorized	Missing or invalid JWT token
`403`	Forbidden	Valid token but insufficient permissions
`404`	Not Found	Resource does not exist
`409`	Conflict	Duplicate resource or state conflict
`422`	Unprocessable Entity	Request body fails validation (Pydantic)
`429`	Too Many Requests	Rate limit exceeded (100 req/min)
`500`	Internal Server Error	Unexpected server failure
`502`	Bad Gateway	Upstream service unreachable (via API gateway)
`503`	Service Unavailable	Service is starting up or unhealthy

Common Error Scenarios

Authentication Errors


# Missing token
curl http://localhost:8000/compliance/summary
# → 401 {"detail": "Authorization header required"}
 
# Expired token
curl -H "Authorization: Bearer expired_token" http://localhost:8000/compliance/summary
# → 401 {"detail": "Token has expired"}

Validation Errors


# Missing required field
curl -X POST http://localhost:8000/execute \
  -H "Content-Type: application/json" \
  -d '{}'
# → 422 {"detail": [{"loc": ["body", "agent_type"], "msg": "field required", ...}]}

Rate Limiting


# Too many requests
# → 429 {"detail": "Rate limit exceeded. Try again in 60 seconds."}

When you receive a 429 response, check the X-RateLimit-Reset header for the timestamp when you can retry.

Resource Not Found


# Non-existent resource
curl http://localhost:8000/conversations/nonexistent-id/messages
# → 404 {"detail": "Conversation not found"}

Retry Strategy

Status Code	Retry?	Strategy
`429`	Yes	Wait until `X-RateLimit-Reset`, then retry
`500`	Yes	Exponential backoff (1s, 2s, 4s), max 3 retries
`502/503`	Yes	Wait 5s, retry up to 3 times (service may be starting)
`400/401/403/404/422`	No	Fix the request — these are client errors