R
Docs
API Documentation

Error envelope & status codes

How errors come back and what to do about each one.

1 min read Updated 5/28/2026developer

Envelope shape

Every error response is a JSON object with at minimum an error string. Some endpoints add a code (machine-readable) or a detail (extra context). Validation errors include an issues[] array.

Examples

JSON
{
  "error": "Not found"
}
JSON
{
  "error": "DUPLICATE_LEAD",
  "message": "You already have a referral with this email address.",
  "existingReferralId": "ref_a1b2c3d4"
}
JSON
{
  "error": "Validation failed",
  "issues": [
    { "path": "customerEmail", "message": "Invalid email" }
  ]
}

Status code reference

| Code | Meaning | Notes | |---|---|---| | 200 | OK | Success | | 201 | Created | New resource created | | 202 | Accepted | Queued for async processing (rare) | | 204 | No Content | Successful delete | | 400 | Bad Request | Validation failed (issues[] array) | | 401 | Unauthorized | No / invalid session cookie | | 403 | Forbidden | Logged in but lacks role / tenant access | | 404 | Not Found | Resource doesn't exist (or is hidden from you) | | 409 | Conflict | Duplicate or invalid state transition | | 422 | Unprocessable Entity | Validation that needed context to detect | | 429 | Too Many Requests | Rate-limited (Retry-After header set) | | 500 | Server Error | Unexpected — please report |

Common machine-readable codes

Some endpoints emit a stable code so you can branch on it without parsing English text:

  • DAILY_LIMIT_REACHED — sales agent created > 20 leads in a single day
  • DUPLICATE_LEAD — agent already has a referral for this email
  • RESTAURANT_CLOSED — customer tried to order outside opening hours
  • PAYMENT_FAILED — Stripe declined; see detail for the Stripe reason
The English error field can change between releases for clarity. The code field is part of the public API and won't change without a deprecation notice.

Frequently asked

  • Yes for shape errors (missing field, wrong type). Business-logic violations that needed context to detect (e.g. trying to redeem an expired gift card) return 422.

Related articles