Skip to main content

Error format

All non-2xx responses share a structured shape so clients can parse

them uniformly.

Standard shape

{ "error": "string or array of zod issues" }

The body is JSON; the Content-Type is application/json.

HTTP status conventions

  • 400 Bad Request: validation failed; body is the Zod issue array
  • 401 Unauthorized: missing or invalid session/token
  • 403 Forbidden: authenticated but not allowed (e.g. wrong org)
  • 404 Not Found: project/atom/anchor not found, or hidden by the

caller's access scope

  • 409 Conflict: state transition not allowed (e.g. accepting an

invite already accepted)

  • 410 Gone: invite or token expired
  • 429 Too Many Requests: rate limit; check Retry-After
  • 500 Internal Server Error: unexpected; the message is generic

Zod issue shape

When validation fails, the error field is the issue array from

Zod. Example:

{
  "error": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "undefined",
      "path": ["organizationId"],
      "message": "Required"
    }
  ]
}

Client SDKs render the path + message for the user.

Cross links

  • /docs/api/overview: rate limits, auth