Errors
HTTP status codes and Bolt error handling for API integrations.
Bolt uses standard HTTP status codes. Error responses include a JSON body with details when validation fails.
Common status codes
| Status | Action |
|---|---|
400 | Fix request parameters |
401 | Send the X-API-Key header. On /v1/merchant/ this status means none arrived and the endpoint fell back to a session check (code 1015); on /v1/subscriptions/ and /v3/ it also covers a key that was sent and rejected |
403 | Check the key, not the signature. On /v1/merchant/ the X-API-Key was rejected (code 1005); otherwise you lack permission or scope (code 18) |
404 | Confirm resource ID and environment |
422 | Review field-level validation errors. Inbound HMAC signature failures also arrive here, as code 27 |
429 | Back off and retry with exponential delay |
5xx | Retry; contact support if persistent |
Which status a missing X-API-Key produces depends on the endpoint, not only on the path prefix: POST /v1/merchant/orders answers 403 with 1005, the same as an invalid key. See Response codes for the cases that differ.
Idempotency
Use idempotency keys on payment and order mutations where supported. See Idempotency reference.
Full error catalog
See Bolt error codes for the complete list.