Errors and status codes

Common status code semantics, the standardized response envelope, and error-handling expectations for non-admin API flows.

Response envelope

API routes are being migrated to a standardized JSON envelope. Endpoints that have been migrated return responses in this shape:

Success

{
  "success": true,
  "data": { ... }
}

Error

{
  "success": false,
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE"
}

Common error codes:

Code	Meaning
UNAUTHORIZED	Authentication is missing or the token is invalid.
VALIDATION_ERROR	The request is missing required fields or contains invalid values.
NOT_FOUND	The requested resource does not exist.
INTERNAL_ERROR	An unexpected server-side failure occurred.

Not every endpoint has been migrated yet. Some routes still return ad-hoc JSON shapes. Always check the success field first — if it is present, you can rely on the envelope format above.

Common status code patterns

• 200 / 201: successful read or mutation.
• 400: invalid payload or missing required fields.
• 401: authentication missing or invalid.
• 404: resource not found.
• 409: state conflict (when route-specific logic enforces uniqueness/state).
• 500: unexpected server-side failure.

Error handling guidance

• Check the success field to determine whether the request succeeded.
• Use the code field for programmatic error handling and the error field for user-facing messages.
• Treat all writes as potentially retriable only when idempotency is guaranteed by route semantics.
• Surface response body messages in client logs for operational debugging.
• Prefer route-specific error handling over global assumptions.

Where to verify

Route-specific responses are defined in OpenAPI endpoint docs under the API Reference Endpoints group.