Skip to content
Docs
Docs / REST API / Guides

Errors

MD View as MarkdownPlain text version of this page
Open in ClaudeAsk questions about this page Open in ChatGPTAsk questions about this page

The status codes the API returns, what each one means, and how to handle it.

On this page

Every error is a JSON body with a message, and validation errors add an errors map. Send Accept: application/json on every request so errors always come back as JSON.

Status Meaning What to do
400 A filter, sort or include the endpoint doesn't allow Use one of the values the message lists
401 Missing, invalid or expired token Check the Authorization header, or create a new token
403 The token lacks the permission, or the account can't see the record Use a token with the right permission and scope
404 No such record in your organization Check the id
409 The record can't be changed in its current state Read the message, which says why
422 The request body or parameters failed validation Fix the fields named in errors
429 Over the rate limit Wait for Retry-After seconds
503 Order history is busy Retry after Retry-After seconds

400 Bad Request

You asked a collection for a filter, sort or include it doesn't support. The message names the values it does allow:

JSON 
{
  "message": "Requested filter(s) `status` are not allowed. Allowed filter(s) are `external_id`."
}

Querying collections lists what each collection accepts.

401 Unauthorized

The request carried no token, or the token is invalid, expired or deleted:

JSON 
{
  "message": "Unauthenticated."
}

Common causes:

  • The Authorization header is missing.
  • The header doesn't start with Bearer followed by the token.
  • The token has expired. Franchisee tokens always expire; HQ tokens expire unless they were created to never expire.
  • The token was deleted, or (for a franchisee token) the brand turned off franchisee tokens.

403 Forbidden

The token is valid, but it isn't allowed to do this. Either the token lacks the permission the endpoint needs:

JSON 
{
  "message": "This API token does not have the 'create' ability."
}

or the account that owns the token isn't allowed to act on this record. A franchisee asking for a location outside their own stores gets a 403, as does any account without the role permission for the action. See Token permissions.

404 Not Found

No record with that id exists in your organization:

JSON 
{
  "message": "Record not found."
}

Records in other organizations are never visible, so they also return 404.

409 Conflict

The record exists, but its current state doesn't allow the change. For example, a location can be deleted only once it is pending, or deactivated with no history left to keep:

JSON 
{
  "message": "Cannot delete an active location. Deactivate it first."
}

The message always says why. For locations, the is_deletable and deletable_on fields tell you ahead of time whether, and from when, a delete will succeed.

422 Unprocessable Entity

A field failed validation. message summarizes the first problem, and errors lists every problem by field:

JSON 
{
  "message": "The name field is required.",
  "errors": {
    "name": ["The name field is required."]
  }
}

429 Too Many Requests

The /api/v1 endpoints allow 60 requests per minute per user, shared by all of that user's tokens. Over that, the API answers 429 until the window resets. The Retry-After header says how many seconds to wait.

Back off and retry after that many seconds. To stay under the limit, ask for larger pages (page[size]=100) and cache data that changes rarely.

503 Service Unavailable

The orders endpoints read check-level history, which can be briefly busy:

JSON 
{
  "message": "Order history is busy; try again in a moment."
}

Retry after the number of seconds in the Retry-After header.