Errors — Docs

HTTP error codes, error response format, validation errors, and retry strategies for the Engramma API.

Error response format

The Engramma API uses FastAPI's standard error format.

Validation errors (422):

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

Simple errors (401, 403, 404, etc.):

{
  "detail": "Not authenticated"
}

Field	Type	Description
`loc`	array[string\|integer]	Path to the field that failed (e.g. `["body", "text"]`)
`msg`	string	Human-readable error message
`type`	string	Error type identifier
`input`	any	The value that caused the error (when available)
`ctx`	object	Additional context (when available)

The request body is malformed or cannot be parsed.

Situation	Fix
Invalid JSON body	Check JSON syntax, ensure Content-Type is `application/json`
Missing required Content-Type	Add `-H "Content-Type: application/json"`

Authentication failed or was not provided.

Detail message	Fix
`Not authenticated`	Add `X-API-Key` header or `Authorization: Bearer` header
`Invalid API key`	Verify the API key is correct and active
`Token expired`	Refresh using `POST /v1/auth/refresh`
`Token revoked`	Create a new API key or re-login

Authentication succeeded but the action is not allowed.

Situation	Fix
Insufficient scope	Create a key with broader scopes
Not an organization admin	Ask an org admin to perform the action
Account suspended	Contact support

The resource or endpoint doesn't exist.

Situation	Fix
Wrong URL path	Check the API docs for correct paths
Resource deleted	The pattern/org/user may have been removed

Wrong HTTP method for the endpoint.

Situation	Fix
GET on a POST-only endpoint	Use the correct HTTP method (e.g. `POST /v1/memory/text/retrieve`, not GET)

The request conflicts with current state.

Situation	Fix
Email already registered	Use login instead, or use a different email
Consolidation already running	Wait for the current cycle to complete

The request is well-formed JSON but fails validation.

Common validations	Constraint
`text` field missing	Required on store/retrieve/recall
`text` too long	Max 10,000 characters (store), 5,000 (query)
`top_k` out of range	Must be 1-50 (text endpoints)
`threshold` out of range	Must be 0.5-1.0 (forget endpoint)
`items` too large	Max 50 items (batch-store)
`password` too short	Minimum 12 characters

You've exceeded your plan's quota.

Situation	Fix
Daily query limit reached	Upgrade plan or wait until tomorrow
Pattern storage full	Upgrade plan or delete unused patterns

Rate limit headers:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Something went wrong on our side.

Situation	Fix
Unexpected error	Retry the request with exponential backoff
Persistent failures	Contact support

Recommended retry behavior:

Never retry: