Skip to main content

​
Error format

All errors return a JSON body with a consistent structure: 
{
  "error": {
    "code": "validation_error",
    "message": "agent_id is required",
    "request_id": "req_01j..."
  }
}
FieldTypeDescription
error.codestringMachine-readable error identifier — use this for programmatic handling
error.messagestringHuman-readable description of the error
error.request_idstringUnique request identifier — include when contacting support

​
Error codes

HTTP Statuserror.codeDescription
400validation_errorRequest body is malformed, missing required fields, contains unknown fields, or field values are out of range
401unauthorizedMissing or invalid API key
401forbiddenValid API key, but it lacks the required scope for this endpoint
404not_foundMemory or resource does not exist, or belongs to a different organization
413payload_too_largecontent exceeds 8192 bytes, or the total request body exceeds the size limit
429rate_limitedKey’s request rate exceeded. Respect the Retry-After response header.
500internal_errorUnexpected server error
503queue_unavailableMessage queue temporarily unreachable (write path only)
Both unauthorized (invalid key) and forbidden (missing scope) return HTTP 401. Distinguish them by the error.code field.

​
Examples

​
400 Validation error

{
  "error": {
    "code": "validation_error",
    "message": "agent_id must match [A-Za-z0-9._:-]",
    "request_id": "req_01j..."
  }
}
Common causes: missing required fields, agent_id or user_id containing invalid characters, k out of range, confidence outside 0.0–1.0, unknown fields in the request body.

​
401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or missing api key",
    "request_id": "req_01j..."
  }
}
Your Bearer token is missing, malformed, revoked, or does not exist.

​
401 Forbidden (missing scope)

{
  "error": {
    "code": "forbidden",
    "message": "missing required scope: memory:write",
    "request_id": "req_01j..."
  }
}
Your API key is valid but was created without the required scope. Create a new key with the correct scopes in the dashboard.

​
413 Payload too large

{
  "error": {
    "code": "payload_too_large",
    "message": "content exceeds maximum length of 8192 bytes",
    "request_id": "req_01j..."
  }
}

​
429 Rate limited

{
  "error": {
    "code": "rate_limited",
    "message": "rate limit exceeded",
    "request_id": "req_01j..."
  }
}
Response headers: Retry-After: 1 (seconds to wait before retrying). Both SDKs handle this automatically.

​
Retry guidance

StatusRetry?Notes
400NoFix the request body before retrying
401NoFix the API key or scope
404NoThe resource does not exist
413NoReduce content size
429YesWait Retry-After seconds, then retry
500YesRetry with exponential backoff
502, 503, 504YesTransient infrastructure issue — retry with backoff