Cómo se ve un rechazo
Un rechazo es application/problem+json, RFC 9457:
| Campo | Qué es |
|---|---|
type | Un código estable para decidir, como insufficient_scope. |
title | Un resumen breve para personas. |
status | El estado HTTP. |
detail | Qué pasó en este caso y qué hacer. |
title y detail vienen en el idioma de Accept-Language — español, inglés o ruso, inglés por defecto — y su redacción puede cambiar: decidí solo según type. Algunos tipos agregan campos, como errors de un error de validación o current, el estado actual del registro, de un conflicto.
Cada respuesta trae el encabezado X-Request-Id. Guardalo en tu log: con él se encuentra la solicitud en el registro de solicitudes de la aplicación.
Errores de validación
La entrada es estricta: un valor incorrecto, un campo que falta y un campo o parámetro desconocido reciben 422 validation_error. errors lista los mensajes por campo; los campos anidados se unen con puntos, como 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."
]
}
}Estados
| Estado | Significado | Qué hacer |
|---|---|---|
| 401 | El token falta, es inválido, venció o fue revocado. | Corregí el token: un reintento no sirve. |
| 403 | A la aplicación le falta un scope, la dirección no está permitida o el plan no tiene API. | Cambiá el acceso de la aplicación en la tienda. |
| 404 | No existe ese registro — o es de otra tienda. | Revisá el ID. |
| 409 | La solicitud choca con el estado de la tienda: se alcanzó un tope, un ID está ocupado, la tienda rechazó el cambio. | Leé type y current y después decidí. |
| 410 | Venció el cursor de sincronización. | Sincronizá de nuevo sin cursor — paginación y sincronización. |
| 412, 428 | La versión en If-Match es vieja o falta. | Leé el registro y repetí — versiones e If-Match. |
| 422 | La solicitud es inválida. | Corregí los campos de errors. |
| 429 | Se agotó el límite de solicitudes. | Esperá Retry-After segundos — límites de solicitudes. |
| 500, 503 | Una falla de nuestro lado o mantenimiento. | Reintentá después de Retry-After con el mismo Idempotency-Key. |
503 store_frozen | La tienda está congelada por una suscripción impaga. | Reintentar no ayuda: la tienda tiene que pagar la suscripción, y las solicitudes vuelven a funcionar enseguida. |
Qué reintentar
- Un error de red o un timeout: repetí la misma solicitud con el mismo
Idempotency-Key. Si se había aplicado, recibís la respuesta guardada — idempotencia. - 429 y 503: después de
Retry-Aftersegundos. - 409
idempotency_key_in_use: la primera solicitud con esta clave todavía corre; repetí después deRetry-After. - 503
transient_conflict: un cambio concurrente revirtió la solicitud y no se escribió nada; repetila. - Cualquier otro 4xx: no tal cual — primero cambiá la solicitud.
Todos los tipos de error
Cada type con su estado, su significado y qué hacer está en el catálogo de errores.