Errors
The error format, every error code the Public API returns, and what to do about each.
Questi contenuti non sono ancora disponibili nella tua lingua.
A failed request returns a non-2xx HTTP status and a JSON body with an errors list:
{ "errors": [ { "code": "validation_failed", "field": "customer.email", "message": "The customer.email field must be a valid email address." } ]}| Key | Meaning |
|---|---|
code | A fixed word. Use it in your code. It never changes within v1. |
message | A sentence for people. Do not depend on its exact wording. |
field | Present when the error is about one input, such as items.0.variant_id. |
Decide what to do from the HTTP status and code, and log message.
Error codes
Section titled “Error codes”| Status | Code | Meaning and what to do |
|---|---|---|
| 401 | unauthorized | No API key was sent. Add the X-SAMITA-API-KEY header. |
| 401 | invalid_api_key | The key is wrong, revoked or expired, or the app was uninstalled. Check the key on the Public API page, or create a new one. |
| 403 | insufficient_scope | The key lacks the permission this endpoint needs. Create a new key with it — permissions can't be edited. |
| 403 | plan_upgrade_required | The store's plan does not include the Public API. Upgrade to PRO or above. |
| 403 | not_available | The API is not available for this store. Contact support. |
| 403 | cors_not_supported | The request came from a browser. Call the API from your server. |
| 403 | quote_limit_reached | The store has used its plan's monthly quote limit, so no new quote can be created. Upgrade, or wait for the next month. |
| 404 | not_found | The quote does not exist in this store, or the path is wrong. A quote from another store gives the same answer. |
| 405 | method_not_allowed | That HTTP method is not supported on this path. |
| 409 | idempotency_conflict | A request with the same Idempotency-Key is still being processed. Wait a moment and retry. |
| 422 | validation_failed | An input is missing or wrong. field and message say which. Fix it and resend. |
| 429 | rate_limited | Too many requests, or too many failed key attempts. Wait Retry-After seconds. |
| 500 | internal_error | Something went wrong on our side. Retry later, and contact support if it keeps happening. |
| 503 | shopify_unavailable | The products could not be loaded from Shopify while creating a quote. Try again in a moment. |
Other unexpected statuses return request_failed.
Which errors to retry
Section titled “Which errors to retry”| Retry automatically | Fix first, then retry |
|---|---|
429 (after Retry-After), 503, 500, 409 | 401, 403, 404, 405, 422 |
When you retry a POST /quotes, send the same Idempotency-Key so a repeat can never create the quote twice. See Quotes.
Troubleshooting
Section titled “Troubleshooting”| You see | Try this |
|---|---|
invalid_api_key right after creating a key | Copy the key again from your password manager. Check for a missing character or a trailing space. |
unauthorized although you set a header | Check the header name is exactly X-SAMITA-API-KEY, or use Authorization: Bearer. A key in the URL is ignored. |
cors_not_supported from a tool | Some tools add an Origin header. Call from a server-side step instead. |
not_found on a quote you can see in the app | Use the quote's id, not its number. List quotes to find the right id. |
validation_failed on fields.* | The key is not on your quote form. Call GET /form for the exact field keys. See Quote form. |
Next steps
Section titled “Next steps”- Requests and responses — limits and paging
- Quotes — endpoints in detail