Stell API errors and status codes

The API uses conventional HTTP status codes: 2xx for success, 4xx for something wrong with the request, and 5xx for a problem on Stell’s side.

Error response format

Every error returns a JSON body with the same shape:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "details": {}
  },
  "requestId": "01JXAMPLE0000000000000000"
}

error.code: a machine-readable code your integration can branch on.
error.message: a human-readable explanation of what went wrong.
error.details: additional context when available, such as which field failed validation.
requestId: a unique identifier for the request. Include it when you contact support about a failed call. It lets us find the exact request in our logs.

Status	Code	Meaning
`200 OK`	n/a	The request succeeded.
`201 Created`	n/a	The resource was created. Returned by create endpoints such as issuing a pass.
`204 No Content`	n/a	The request succeeded and there is nothing to return, typical for deletes.
`400 Bad Request`	`BAD_REQUEST`	The request is malformed: missing required fields, wrong types, invalid JSON.
`400 Bad Request`	`VALIDATION_ERROR`	A field failed validation against its own rules, such as an unrecognized field, a phone number not in E.164 format, an enum value outside the accepted set. Check `error.details` for the offending field.
`401 Unauthorized`	`UNAUTHORIZED`	The API key is missing, invalid, expired, or revoked. See Authentication.
`403 Forbidden`	`FORBIDDEN`	The key is valid but the resource belongs to another company.
`404 Not Found`	`NOT_FOUND`	The resource doesn’t exist, often because of a mistyped or stale ID.
`409 Conflict`	`CONFLICT`	The request conflicts with the resource’s current state, for example updating a voided or expired pass, or deleting a merchant that still has stores. `error.message` names the specific rule.
`429 Too Many Requests`	n/a	You’re sending requests faster than the API allows. Back off and retry with a delay.
`500 Internal Server Error`	`INTERNAL_ERROR`	Something went wrong on Stell’s side. Retry with backoff; if it persists, contact support with the `requestId`.
`503 Service Unavailable`	n/a	The API is temporarily unavailable. Retry with backoff.

Branch on error.code, not on error.message. Messages can change, codes won’t.
Retry 5xx and 429 responses with exponential backoff. Don’t retry 4xx responses unchanged; fix the request first.
Log the requestId for every failed call so support conversations start with the right context.