What an error looks like
An error is application/problem+json, RFC 9457:
| Field | What it is |
|---|---|
type | A stable code to branch on, such as insufficient_scope. |
title | A short summary for people. |
status | The HTTP status. |
detail | What 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.
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"
}'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
| Status | Meaning | What to do |
|---|---|---|
| 401 | The token is missing, invalid, expired or revoked. | Fix the token: a retry does not help. |
| 403 | The app lacks a scope, the address is not allowed or the plan has no API. | Change the access of the app in the store. |
| 404 | There is no such record — or it belongs to another store. | Check the ID. |
| 409 | The 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. |
| 410 | The sync cursor expired. | Sync again without a cursor — pagination and sync. |
| 412, 428 | The version in If-Match is old or missing. | Read the record and repeat — versions and If-Match. |
| 422 | The request is invalid. | Fix the fields from errors. |
| 429 | The rate limit is exhausted. | Wait Retry-After seconds — rate limits. |
| 500, 503 | A failure on our side or maintenance. | Retry after Retry-After with the same Idempotency-Key. |
503 store_frozen | The 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-Afterseconds. - 409
idempotency_key_in_use: the first request with this key is still running; repeat afterRetry-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.