Error responses
One shape, stable codes, and what to do about each.
1 min readUpdated View as Markdown
Errors are JSON with a machine-readable error and a human message:
{ "error": "origin_not_allowed", "message": "Origin 'https://other.site' is not in the allowed origins list" }Branch on error (and the status), never on message: messages may be reworded, codes never are within v1.
Gateway errors
| Status | error |
Meaning | What to do |
|---|---|---|---|
| 401 | api_key_required |
No X-API-Key header. |
Send the key. |
| 401 | invalid_api_key_format |
The value is not a key. | Check for whitespace or a truncated value. |
| 401 | invalid_api_key |
No such key. | It was deleted or regenerated. Use the current one. |
| 403 | api_key_inactive |
The key is switched off. | Turn it on, or use another. |
| 403 | organization_shutdown |
The organization is shut down. Includes shutdown_at. |
Contact support. |
| 403 | origin_not_allowed |
Live public key from an origin not on its list. | Add the host under Allowed origins (bare host, no https://). |
| 403 | secret_key_required |
An admin route called with a public key. | Call it from your server with the secret key. |
| 405 | (empty body) | Wrong method for this path. | See the Allow header. |
| 429 | Rate limit exceeded |
Too many requests this minute. | Wait retry_after seconds. |
| 501 | not_implemented |
The route exists in v1 but is not built on the new platform yet. Includes "available": false. |
Do not retry. |
| 503 | not_available_yet |
The route is held back for this organization (for example, customer data for a HIPAA organization whose HIPAA path is not complete). Includes "available": false and a reason. |
Do not retry. |
Service errors (a product not found, a validation problem) use the same shape, for example 404 {"error": "not_found", "message": "Product not found"} or 400 {"error": "validation_error", "message": "name is required"}.
In the SDK
Every failure is a DashApiError with status, code (the error value, or network_error, timeout, aborted, invalid_response), fields (for validation errors), requestId and retryable. GET requests retry automatically on network errors, timeouts, 408, 425, 429, 502, 503 and 504, honoring Retry-After. Writes are never retried automatically.
Keep reading
Something wrong or missing on this page? Email support@dashfordevs.com.