Errors

Failed requests return a non-2xx status and a JSON body with one shape.

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found."
  }
}

Branch on error.code. The message is for people and can change.

Validation errors

When a request body is invalid, the status is 422 and error.fields lists the problems per field.

{
  "error": {
    "code": "validation_failed",
    "message": "The attention field is required.",
    "fields": {
      "attention": ["The attention field is required."],
      "address1": ["The address1 field is required."]
    }
  }
}

For nested input, field names use dots, such as items.0.quantity.

Error codes

Status	Code	Meaning
401	`missing_api_key`	No bearer token was sent.
401	`invalid_api_key`	The key is unknown, revoked or expired.
403	`account_suspended`	The account that owns the key is suspended.
403	`insufficient_scope`	The key lacks the scope, or the owner’s role no longer allows it.
403	`forbidden`	The owner’s role does not allow this action.
404	`not_found`	The record does not exist, or the key is not allowed to see it.
422	`validation_failed`	The request body failed validation. See `error.fields`.

Rate limits

Each key has its own limit, 60 requests per minute by default. When you exceed it, the API returns 429 with a Retry-After header holding the seconds to wait. Do not rely on the body of a 429 response; use the status and the header. Back off and retry after the delay. Spread bulk syncs over time, and use limit=100 to cut the number of requests.

Getting started

Essentials

Validation errors

Error codes

Rate limits

​Validation errors

​Error codes

​Rate limits

Validation errors

Error codes

Rate limits