# Errors

> The error format, every error code the Public API returns, and what to do about each.

App: SA Request a Quote, Hide Price (Shopify app by Samita)
Source: https://docs.samita.io/sa-request-a-quote/public-api/errors
Last updated: 2026-11-18

A failed request returns a non-2xx HTTP status and a JSON body with an `errors` list:

```json
{
  "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

| 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

| 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](https://docs.samita.io/sa-request-a-quote/public-api/quotes#create-a-quote).

## 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

* [Requests and responses](https://docs.samita.io/sa-request-a-quote/public-api/requests-and-responses) — limits and paging
* [Quotes](https://docs.samita.io/sa-request-a-quote/public-api/quotes) — endpoints in detail
