Docs · Guías

Errores y reintentos

Los errores son problem details según RFC 9457. Cada uno tiene un type que dice qué salió mal y un indicador retryable que dice si volver a intentarlo.

Problem details

Las respuestas de error usan application/problem+json. Decide qué hacer a partir de type y retryable, no de title ni de detail, que son para personas.

403 · application/problem+json

{
  "type": "https://developers.novo.co/problems/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This client does not have the cards:freeze scope.",
  "request_id": "req_example_01",
  "retryable": false
}

typestringobligatorio

Identifica el error. Usa este campo, no el título, para decidir qué hacer

uri

titlestringobligatorio

Resumen breve y legible

statusintegerobligatorio

El código de estado HTTP

detailstring

Explicación de este caso concreto

instancestring

Identifica este caso concreto

request_idstringobligatorio

Igual que el encabezado Novo-Request-Id. Indícalo al contactar con soporte

retryablebooleanobligatorio

Si se puede reintentar la misma solicitud, después de Retry-After cuando lo hay

type es una URI absoluta que lleva a la página de ese error (consulta Tipos de problema). El host de la documentación aún no es definitivo Por definir, y los nombres cortos de abajo son propuesto. El endpoint de tokens es la excepción: responde con errores de OAuth 2.0 (consulta Autenticación).

Tipos de error

TipoEstadoReintentoSignificado

invalid-token401NoFalta el token, está mal formado o es desconocido

token-expired401NoEl token venció. Obtén uno nuevo y envía la solicitud otra vez

client-disabled401NoEl cliente se revocó, se suspendió o se desactivó

insufficient-scope403NoEl cliente no tiene el scope que necesita esta llamada

owner-standing-lost403NoEl titular al que está vinculado este cliente ya no tiene el rol de titular, o su perfil ya no permite el acceso

feature-not-enabled403NoLa API no está habilitada para este negocio

invalid-parameter400NoUn parámetro no es válido, por ejemplo un card_id que no es un UUID, o el cuerpo no es JSON válido

not-found404NoNo hay nada con ese id en el negocio vinculado

idempotency-key-reused409NoEl Idempotency-Key ya se usó con otra solicitud

idempotency-in-progress409Después de Retry-AfterLa primera solicitud con esta clave todavía está en curso

card-state-conflict409NoLa tarjeta está en un estado que no permite congelarla

payload-too-large413NoEl cuerpo de la solicitud es demasiado grande. El límite de tamaño se indicará en esta documentación cuando se fije

unsupported-media-type415NoLa operación no acepta el tipo de contenido o el charset del cuerpo de la solicitud

rate-limited429Después de Retry-AfterDemasiadas solicitudes para este cliente o negocio

internal-error500NoAlgo falló de forma inesperada del lado de Novo. El cuerpo no incluye detalles internos

dependency-unavailable503Después de Retry-AfterAhora mismo no se puede cargar una parte de la respuesta

Cuándo reintentar

Reintenta solo cuando retryable sea true, y espera lo que indique Retry-After cuando esté presente.
503 siempre significa un problema temporal del lado de Novo. Un cliente revocado o desactivado es un 401, nunca un 503, así que un bucle que reintenta con 503 no puede seguir insistiendo con un cliente muerto.
Con token-expired, pide un token nuevo y repite la llamada. Con cualquier otro 401 o 403, detente: reintentar no cambiará la respuesta.
Si usas un agente, dale esta regla en lugar de dejar que reintente con cada error.

Límites de solicitudes

Los límites se aplican por cliente y por negocio. Cuando los superas, la API devuelve 429 con Retry-After, además de los encabezados RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset. Las cifras están Por definir. El endpoint de tokens tiene su propio límite, así que guarda tu token de acceso en caché durante toda su vida.

Idempotencia

Congelar una tarjeta acepta un encabezado Idempotency-Key: un valor que eliges tú, de hasta 255 caracteres, como un UUID. Se recomienda, pero no es obligatorio. De todos modos, congelar es seguro de repetir: congelar una tarjeta ya congelada devuelve 200.

Envía la misma clave cuando reintentes la misma solicitud, y una clave nueva para una solicitud nueva.
Si la clave ya se usó con otra solicitud, recibes 409 idempotency-key-reused.
Si la primera solicitud con esa clave todavía está en curso, recibes 409 idempotency-in-progress. Reintenta después de Retry-After.
Las claves se guardan durante 24 horas propuesto.