GETTING STARTED

Errors

The API uses conventional HTTP status codes, plus a JSON envelope that carries a machine code and human message.

Shape

ErrorResponse.json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "priority must be one of low, normal, high, urgent",
    "details": { "field": "priority" }
  }
}

Status codes

400

Validation failed. See the message and details for specifics.

401

Missing or invalid API key.

403

Authenticated user lacks the required permission for this resource.

404

The requested resource was not found.

409

Conflict with the current state of the resource.

429

Some endpoints may reject bursts, throttled clients, or quota overruns with 429 responses.

5xx

Unexpected server-side failure. Idempotent requests are usually the safest to retry.

Reliability guidance

Always inspect error.code; messages are human-oriented and may change.
On 5xx — and on 429 where an endpoint emits it — back off exponentially before retrying.
Be more conservative retrying non-idempotent operations such as POST, especially if your integration cannot safely deduplicate repeats.