Errores

Todos los errores de la API tienen la misma forma. El código HTTP dice la clase de problema; el código del cuerpo, cuál fue exactamente.

La forma de un error

Una respuesta con error trae siempre un objeto error con estos campos:

Campos de un error
Campo	Qué trae
`codigo`	Un identificador fijo, de la tabla de abajo. Es lo que tiene que mirar tu código: el mensaje puede cambiar de redacción.
`mensaje`	Una explicación en castellano, pensada para mostrarla o dejarla en un registro.
`pedido`	El identificador del pedido. Es el mismo valor del encabezado `x-kaptativa-pedido`.
`detalles`	Solo cuando la entrada no es válida: una lista con el `campo` y el `mensaje` de cada problema.

Un campo que no cumple el esquema, 422

{
  "error": {
    "codigo": "entrada",
    "mensaje": "email: Invalid email address",
    "pedido": "ped_3f9a1c0b7d2e4f6a8b1c2d3e4f5a6b7c",
    "detalles": [
      {
        "campo": "email",
        "mensaje": "Invalid email address"
      }
    ]
  }
}

Un registro que no está, 404

{
  "error": {
    "codigo": "no_encontrado",
    "mensaje": "No existe o no es de esta cuenta.",
    "pedido": "ped_8c2d4e6f0a1b3c5d7e9f1a2b3c4d5e6f"
  }
}

Toda respuesta de la API a un pedido con token, con error o sin él y también el 401 de un token que no pasa, lleva el encabezado x-kaptativa-pedido con un valor como ped_3f9a1c0b7d2e4f6a8b1c2d3e4f5a6b7c. Guardalo en tus registros junto con cada llamada: si algo no cierra, con ese valor encontramos el pedido de nuestro lado. La única que no lo trae es GET /v1/openapi.json, que es pública y se pide sin token.

Códigos

Códigos de error de la API
HTTP	Código	Qué pasó	Qué hacer
400 o 413	`cuerpo`	El cuerpo del pedido no es JSON válido o, en un recurso, no es un objeto. Si pasa el tamaño máximo, el mismo código con 413.	Corregí el cuerpo. No lo reintentes igual.
401	`token`	Falta el token, está mal copiado, venció, se revocó o su persona ya no está en la cuenta.	Revisá el encabezado Authorization o creá un token nuevo.
403	`no_activo`	La cuenta no está activa, no tiene la API o no tiene activo el submódulo de esa operación.	Se resuelve en la cuenta, no en el pedido.
403	`audiencia`	Esa operación no está disponible para un token.	No se puede hacer por la API.
403	`sin_permiso`	La persona dueña del token no tiene ese permiso.	Se cambia en el perfil de la persona, en el panel.
403	`alcance`	El token no tiene el alcance que pide la operación.	Usá un token con ese alcance.
403	`sensible`	La operación lee datos sensibles, que no salen por la API.	No se puede hacer por la API.
404 o 405	`no_existe`	La ruta o la operación no existe, o no se ofrece por la API. Si la ruta existe pero no con ese método, el mismo código con 405 y el encabezado Allow.	Revisá el método y la ruta contra la referencia.
404	`no_encontrado`	El registro que pediste por id o código no existe o no es de esta cuenta.	Revisá el id. No distingue entre "no existe" y "es de otra cuenta" a propósito.
409	`servicio`	Una regla del negocio no lo deja: un código repetido, un estado que no admite ese cambio.	El mensaje lo explica. Reintentar igual da lo mismo.
409 o 422	`idempotencia`	La clave de idempotencia ya se usó: el primer pedido sigue en curso (409) o la mandaste con otro pedido (422). También 422 si la clave no es válida.	Mirá Idempotencia.
422	`entrada`	Los campos del pedido (del cuerpo, de la consulta o de la ruta) no cumplen el esquema de la operación, o el cursor no es válido.	Mirá detalles: dice qué campo y por qué.
429	`limite`	Pasaste los pedidos por minuto del token o de la cuenta.	Esperá los segundos de Retry-After y reintentá.
500	`interno`	Algo falló de nuestro lado. Quedó registrado.	Reintentá en un rato. Si sigue, abrí un ticket con el identificador del pedido.

Un cuerpo de más de 100 KB responde 413 con el código cuerpo, sin ejecutarse. Un método que la ruta no admite responde 405 con el código no_existe y el encabezado Allow con los que sí.

Cuando sale bien, la respuesta es siempre 200, también al crear: no hay 201 ni 204.

Qué reintentar y qué no

Reintentá un 429 después de los segundos de Retry-After, y un 500 o un corte de conexión con espera creciente (por ejemplo 1, 2, 4 y 8 segundos).
No reintentes los demás errores 4xx sin cambiar algo: van a responder lo mismo.
Si el pedido cambia algo, reintentalo siempre con la misma clave de idempotencia. Así un pedido que sí llegó, pero cuya respuesta se perdió, no se ejecuta dos veces.

Mirá el código, no el mensaje

Los valores de codigo son parte del contrato de la v1 y no cambian. Los mensajes se pueden mejorar sin aviso.

La forma de un error

El identificador del pedido

Códigos

Qué reintentar y qué no