Error Response Format

All API errors return a JSON object with an error field:

json

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

Some endpoints include additional fields:

json

{
  "error": "Quota exceeded",
  "resource": "aiTokens",
  "current": 1050000,
  "limit": 1000000,
  "source": "plan"
}

HTTP Status Codes

Success Codes

Code	Meaning	When
`200`	OK	Successful GET, PATCH, DELETE
`201`	Created	Successful POST that creates a resource
`202`	Accepted	V2 ingest — event accepted for processing
`204`	No Content	CORS preflight, successful delete with no body
`304`	Not Modified	Brain document unchanged (ETag match)

Client Error Codes

Code	Meaning	Common Causes
`400`	Bad Request	Invalid JSON, missing required fields, validation error
`401`	Unauthorized	Missing or invalid API key, expired session
`403`	Forbidden	Insufficient permissions (RBAC), quota exceeded, HMAC validation failed
`404`	Not Found	Resource doesn't exist or you don't have access
`409`	Conflict	Duplicate resource (idempotence check), version conflict
`422`	Unprocessable Entity	Valid JSON but semantically invalid (e.g., invalid schemaKey format)
`429`	Too Many Requests	Rate limit exceeded (200 req/min). Check `Retry-After` header

Server Error Codes

Code	Meaning	What to Do
`500`	Internal Server Error	Retry after a moment. If persistent, contact support
`502`	Bad Gateway	Temporary infrastructure issue. Retry
`503`	Service Unavailable	Maintenance or overload. Check status page

Rate Limiting Headers

When rate limited (429), the response includes:

Retry-After: 60
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0

Common Error Scenarios

Authentication Errors

json

// Missing API key
{ "error": "Unauthorized" }

// Invalid API key
{ "error": "Invalid API key" }

// HMAC validation failed
{ "error": "Invalid HMAC signature" }

// Timestamp too old (anti-replay)
{ "error": "Timestamp too far from server time" }

Quota Errors

json

// Plan limit reached
{
  "error": "Quota exceeded for resource: aiTokens",
  "resource": "aiTokens",
  "current": 1050000,
  "limit": 1000000,
  "source": "plan"
}

// No credits available
{
  "error": "Quota exceeded and no prepaid credits available",
  "resource": "aiTokens"
}

Validation Errors

json

// Missing required field
{ "error": "name is required" }

// Invalid field value
{ "error": "visibility must be 'public' or 'private'" }

// Content too large
{ "error": "content exceeds maximum length of 50000 characters" }

Permission Errors

json

// Insufficient role
{ "error": "Forbidden: requires admin role" }

// Not a project member
{ "error": "Not a member of this project" }

Data Model

Limits

On this page