Errores

Cada rechazo de la API tiene la misma forma y un código estable. Decidí según el código, mostrale el texto a las personas y reintentá solo lo que un reintento puede arreglar.

Cargando el índice de búsqueda…

Errores

Cómo se ve un rechazo

Un rechazo es application/problem+json, RFC 9457:

CampoQué es
typeUn código estable para decidir, como insufficient_scope.
titleUn resumen breve para personas.
statusEl estado HTTP.
detailQué 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.

Solicitud
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"
}'
Respuesta
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

EstadoSignificadoQué hacer
401El token falta, es inválido, venció o fue revocado.Corregí el token: un reintento no sirve.
403A 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.
404No existe ese registro — o es de otra tienda.Revisá el ID.
409La 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í.
410Venció el cursor de sincronización.Sincronizá de nuevo sin cursor — paginación y sincronización.
412, 428La versión en If-Match es vieja o falta.Leé el registro y repetí — versiones e If-Match.
422La solicitud es inválida.Corregí los campos de errors.
429Se agotó el límite de solicitudes.Esperá Retry-After segundos — límites de solicitudes.
500, 503Una falla de nuestro lado o mantenimiento.Reintentá después de Retry-After con el mismo Idempotency-Key.
503 store_frozenLa 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-After segundos.
  • 409 idempotency_key_in_use: la primera solicitud con esta clave todavía corre; repetí después de Retry-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.

Siguiente guíaIdempotencia