Saltar al contenido
Vintu API
Tema de la documentación
Ir a la app

Errores

Toda respuesta de error tiene el mismo cuerpo:

Error (datos ficticios)JSON
{
"error": {
  "codigo": "SCOPE_REQUIRED",
  "mensaje": "La clave no tiene el permiso que pide esta operación.",
  "id_peticion": "00000000-0000-4000-8000-000000000001"
}
}
  • codigo es estable: compara contra él.
  • mensaje es una explicación en español para personas. Puede cambiar; no lo uses para decidir nada.
  • id_peticion coincide con la cabecera X-Request-ID, que llevan todas las respuestas, también las correctas. Cítalo al escribir a soporte.

Códigos

Los códigos son los del enum de ErrorDetails.codigo del OpenAPI; el estado y la descripción salen de las respuestas que los citan.

Código Estado Cuándo
INVALID_API_KEY 401

Clave ausente, mal formada, inexistente o revocada (INVALID_API_KEY).

FORBIDDEN 403

Permiso o plan insuficiente por un motivo distinto de SCOPE_REQUIRED, API_PLAN_REQUIRED o ACCESS_DENIED.

NOT_FOUND 404

El recurso no existe o no es de esta cuenta (NOT_FOUND).

CONFLICT 409

Reservado para escrituras, que v1 no tiene.

VALIDATION_ERROR 422

Parámetro inválido (VALIDATION_ERROR), cursor de otra consulta (INVALID_CURSOR) o cursor caducado a las 24 horas (CURSOR_EXPIRED).

El archivo supera los 25 MiB (FILE_TOO_LARGE) o el enlace está mal formado (VALIDATION_ERROR).

INVALID_CURSOR 422

Parámetro inválido (VALIDATION_ERROR), cursor de otra consulta (INVALID_CURSOR) o cursor caducado a las 24 horas (CURSOR_EXPIRED).

CURSOR_EXPIRED 422

Parámetro inválido (VALIDATION_ERROR), cursor de otra consulta (INVALID_CURSOR) o cursor caducado a las 24 horas (CURSOR_EXPIRED).

INVALID_FILE_TOKEN 401

Enlace inválido, vencido o de una clave revocada (INVALID_FILE_TOKEN). Vuelve a pedir el comprobante para obtener uno nuevo.

RATE_LIMITED 429

Se superó el límite de peticiones (RATE_LIMITED). Espera lo que indica Retry-After.

DEPENDENCY_UNAVAILABLE 503

Servicio no disponible temporalmente (DEPENDENCY_UNAVAILABLE o LOCAL_CAPACITY). Reintenta tras Retry-After.

COORDINATION_UNAVAILABLE 503

Reservado para escrituras, que v1 no tiene.

LOCAL_CAPACITY 503

Servicio no disponible temporalmente (DEPENDENCY_UNAVAILABLE o LOCAL_CAPACITY). Reintenta tras Retry-After.

REQUEST_REJECTED 4xx

La petición se rechazó antes de llegar a una operación, por ejemplo con un método distinto de GET (405). El estado HTTP es el de esa causa.

SCOPE_REQUIRED 403

La clave no tiene el permiso de la operación (SCOPE_REQUIRED), el plan no incluye la API (API_PLAN_REQUIRED) o la cuenta no tiene acceso activo (ACCESS_DENIED).

API_PLAN_REQUIRED 403

La clave no tiene el permiso de la operación (SCOPE_REQUIRED), el plan no incluye la API (API_PLAN_REQUIRED) o la cuenta no tiene acceso activo (ACCESS_DENIED).

ACCESS_DENIED 403

La clave no tiene el permiso de la operación (SCOPE_REQUIRED), el plan no incluye la API (API_PLAN_REQUIRED) o la cuenta no tiene acceso activo (ACCESS_DENIED).

FILE_TOO_LARGE 422

El archivo supera los 25 MiB (FILE_TOO_LARGE) o el enlace está mal formado (VALIDATION_ERROR).

Qué hacer con cada estado

EstadoQué hacer
401No reintentes con la misma clave. Revisa la cabecera o crea otra clave. En una descarga (INVALID_FILE_TOKEN), pide el comprobante otra vez para obtener un enlace nuevo.
403No reintentes. Falta un permiso en la clave (SCOPE_REQUIRED), el plan no incluye la API (API_PLAN_REQUIRED) o la cuenta no tiene acceso activo (ACCESS_DENIED).
404El recurso no existe o no es de tu cuenta; la API no distingue entre los dos casos.
422Corrige la petición. Con CURSOR_EXPIRED, vuelve a la primera página; con INVALID_CURSOR, repite los mismos filtros que la página anterior.
429Espera los segundos de Retry-After y reintenta. Ver Límites de uso.
503Fallo pasajero del servicio. Espera los segundos de Retry-After y reintenta.

Una respuesta 200 nunca lleva un error dentro: si el estado es 2xx, el cuerpo es el recurso.