Errors

AEGIS API errors return a JSON body. The key depends on where the error was raised:

Backend services (FastAPI) return {"detail": "..."}.
The gateway itself (missing/invalid auth, forbidden role, rate limit, upstream unreachable) returns {"error": "..."}.

Error Response Format


// Backend service error (FastAPI)
{
  "detail": "Human-readable error description"
}


// Gateway error (auth, rate limit, role gate)
{
  "error": "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

Auth errors are raised by the gateway, so they use the {"error": ...} key:


# Missing token
curl http://localhost:8000/api/v1/compliance/summary
# → 401 {"error": "missing authentication: provide an Authorization Bearer token or aegis_token cookie"}
 
# Invalid / expired token
curl -H "Authorization: Bearer expired_token" http://localhost:8000/api/v1/compliance/summary
# → 401 {"error": "invalid token: token has expired"}
 
# Auth service temporarily unreachable (perimeter can't resolve the token)
# → 503 {"error": "authorization service unavailable"}

A resolver outage returns 503, not 401, so clients distinguish “we can’t authorize you right now” (transient — retry) from “your session is invalid” (re-login). A 401 here would hard-logout every active user on a transient auth-service blip.

Validation Errors


# Missing required field (conversation_id and message are required on /execute)
curl -X POST http://localhost:8000/api/v1/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
# → 422 {"detail": [{"loc": ["body", "conversation_id"], "msg": "field required", ...}]}

Rate Limiting


# Too many requests (gateway error key)
# → 429 {"error": "rate limit exceeded — 600 requests/minute"}

The gateway does not return Retry-After or X-RateLimit-* headers. Plan retries around the fixed 600 req/min (burst 100) limit with exponential backoff.

Resource Not Found


# Non-existent resource
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/conversations/nonexistent-id/messages
# → 404 {"detail": "Conversation not found"}

Retry Strategy

Status Code	Retry?	Strategy
`429`	Yes	Exponential backoff (1s, 2s, 4s); no `Retry-After` header is sent
`500`	Yes	Exponential backoff (1s, 2s, 4s), max 3 retries
`502/503`	Yes	Wait 5s, retry up to 3 times (service may be starting, or a transient resolver blip)
`400/401/403/404/422`	No	Fix the request — these are client errors