Error Codes

Use the JSON response body first. MaaS runtime errors are intentionally short.

400 Bad Request

Common causes:

• API key is missing or invalid
• X-Workspace-Id is missing
• request body is malformed

{
  "error": "bad_request",
  "message": "X-Workspace-Id is required"
}

Resolution:

• send a valid Authorization or x-api-key
• send X-Workspace-Id
• validate JSON before retry

402 Payment Required

Common cause:

• billing account is blocked or delinquent

{
  "error": "billing_access_blocked",
  "message": "runtime access is blocked for this billing account"
}

Resolution:

• fix billing status
• retry after the account is active

403 Forbidden

Common cause:

• access policy denies this key/workspace combination

{
  "error": "forbidden",
  "message": "runtime access denied by access policy"
}

Resolution:

• verify the key belongs to the intended tenant
• verify the workspace id matches the allowed runtime scope

404 Not Found

Common cause:

• requested anchor or recall session does not exist

{
  "error": "not_found",
  "message": "anchor not found"
}

Resolution:

• create the anchor first with POST /v1/anchors
• do not assume an anchor exists after checkout

429 Too Many Requests

Common cause:

• request rate exceeded for the current key/workspace

{
  "error": "rate_limited",
  "message": "too many requests"
}

Resolution:

• retry with exponential backoff
• reduce fan-out and duplicate recall calls