Errors

Every error of the API has the same shape and a stable code. Branch on the code, show the text to people, and retry only what a retry can fix.

Loading the search index…

Errors

What an error looks like

An error is application/problem+json, RFC 9457:

FieldWhat it is
typeA stable code to branch on, such as insufficient_scope.
titleA short summary for people.
statusThe HTTP status.
detailWhat happened in this case and what to do.

title and detail are in the language of Accept-Language — Spanish, English or Russian, English by default — and their wording may change: branch only on type. Some types add fields, such as errors of a validation error or current, the state of the record now, of a conflict.

Every response has an X-Request-Id header. Write it to your log: by it the request is found in the request log of the app.

Validation errors

The input is strict: a wrong value, a missing field and an unknown field or parameter all get 422 validation_error. errors lists the messages by field; nested fields are joined with dots, such as variants.0.price.

Request
curl -X POST "https://api.saleya.app/v1/inventory-levels/set" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'Idempotency-Key: 0b4a9a3c-6c4e-4f0e-9a43-2f8f6d1b7e21' \
  -H "Content-Type: application/json" \
  -d '{
  "variant_id": 1042,
  "location_id": 3,
  "on_hand": "24"
}'
Response
HTTP/1.1 422 Unprocessable Content

{
  "type": "validation_error",
  "title": "Validation failed",
  "status": 422,
  "errors": {
    "expected_on_hand": [
      "The expected on hand field is required."
    ]
  }
}

Statuses

StatusMeaningWhat to do
401The token is missing, invalid, expired or revoked.Fix the token: a retry does not help.
403The app lacks a scope, the address is not allowed or the plan has no API.Change the access of the app in the store.
404There is no such record — or it belongs to another store.Check the ID.
409The request conflicts with the state of the store: a limit is reached, an ID is taken, the store rejected the change.Read type and current, then decide.
410The sync cursor expired.Sync again without a cursor — pagination and sync.
412, 428The version in If-Match is old or missing.Read the record and repeat — versions and If-Match.
422The request is invalid.Fix the fields from errors.
429The rate limit is exhausted.Wait Retry-After seconds — rate limits.
500, 503A failure on our side or maintenance.Retry after Retry-After with the same Idempotency-Key.
503 store_frozenThe store is frozen for an unpaid subscription.Retrying will not help: the store has to pay its subscription, and requests work again right after that.

What to retry

  • A network error or a timeout: repeat the same request with the same Idempotency-Key. If it went through, you get the saved response — idempotency.
  • 429 and 503: after Retry-After seconds.
  • 409 idempotency_key_in_use: the first request with this key is still running; repeat after Retry-After.
  • 503 transient_conflict: a concurrent change rolled the request back and nothing was written; repeat it.
  • Any other 4xx: not as it is — change the request first.

All error types

Every type with its status, its meaning and what to do is in the error catalog.

Next guideIdempotency