Error handling

Quick diagnosis

Use this decision tree to find the right page for your issue:

Detailed guides

Topic	Page
HTTP status codes, error bodies, client retries	Errors
Search SLAs, terminal conditions, human escalation	SLA and escalation
Common validation and integration issues	Troubleshooting
Auth failures	Authentication — Troubleshooting
Webhook delivery problems	Webhook Integration — Troubleshooting

Error response shape

All API errors return a consistent JSON body:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

The message field may be a string or an array of strings (for multi-field validation failures). Always handle both cases in your client code. See Errors for the full reference.

Retry decision matrix

Scenario	Retry?	Strategy
`5xx` or network timeout	Yes	Exponential backoff (2^attempt seconds)
`400` validation error	No	Fix the request body
`401` authentication error	No	Refresh or request a new JWT
Order create with no response	Maybe	Reconcile by `externalSearchId` first
Webhook handler returned `5xx`	Automatic	SNH AI retries per `retryAttempts` config

Core concepts

Guides

Examples

Troubleshooting

Error handling

Error handling

Quick diagnosis

Detailed guides

Error response shape

Retry decision matrix

​Error handling

​Quick diagnosis

​Detailed guides

​Error response shape

​Retry decision matrix

Error handling

Quick diagnosis

Detailed guides

Error response shape

Retry decision matrix