Desarrolladores
Un código HTTP y un JSON con el motivo.
Los errores de autenticación, permisos y límites siguen el estándar RFC 9457
(Content-Type: application/problem+json):
{
"type": "https://bm.consulting/en/developers/errors#forbidden_permission",
"title": "Forbidden",
"status": 403,
"detail": "This token does not grant sales:invoices.read.",
"code": "forbidden_permission",
"required_permission": "sales:invoices.read",
"error": "Forbidden"
}| Campo | Qué contiene |
|---|---|
type | Enlace a la explicación del error en esta página. |
title · status | Nombre y código HTTP. |
detail | Explicación para personas, en inglés. Puede cambiar. |
code | Código estable para programar contra él (tabla de abajo). |
required_permission | En forbidden_permission: el permiso que exige la ruta. |
scope · window | En rate_limited: el nivel que alcanzó el límite (token, acct o user) y la ventana (minute o month). |
error | Siempre. Se mantiene por compatibilidad: el título, o el mensaje en los errores de validación. |
Los errores de validación de cada operación (400, 404, 409, 422) llevan siempre
error con el motivo; los que devuelve el núcleo de la API usan además el formato de arriba, con
code igual a http_ más el código HTTP.
code | HTTP | Cuándo |
|---|---|---|
unauthorized | 401 | Falta el token, no existe, está desactivado o revocado, o ha caducado. |
account_bound_not_allowed | 403 | La ruta no admite tokens ligados a la cuenta de un cliente. |
forbidden_permission | 403 | El token no tiene el permiso de la ruta; va en required_permission. |
ip_not_allowed | 403 | La petición no viene de una IP de la lista del token. |
rate_limited | 429 | Se alcanzó un límite por minuto o la cuota mensual; ver window, scope y Retry-After. |
Programa tu integración contra el código HTTP y el campo code.
Los textos de detail y error están pensados para personas y pueden cambiar.
| Código | Significado | Cuándo ocurre |
|---|---|---|
400 | Petición mal formada | Un parámetro o el cuerpo no son válidos: JSON inválido, fecha que no es ISO, campo obligatorio ausente, importe con formato incorrecto. |
401 | No autenticado | Falta el token, no existe, está desactivado o revocado, o ha caducado. |
403 | Prohibido | El token no tiene el permiso de la ruta (incluye required_permission), la ruta no admite tokens ligados a una cuenta, la IP no está permitida o el recurso pertenece a otra cuenta. |
404 | No encontrado | El recurso no existe o pertenece a otra cuenta. La API no distingue ambos casos. |
409 | Conflicto | La operación choca con un dato existente; por ejemplo, un identificador de liquidación ya registrado. |
422 | No procesable | El JSON es válido pero un valor no cumple las reglas de negocio: campo obligatorio vacío, referencia desconocida. |
429 | Demasiadas peticiones | Se alcanzó un límite por minuto o la cuota mensual del token, de la cuenta o del usuario. Incluye Retry-After y las cabeceras X-RateLimit-*. |
500 | Error interno | Fallo inesperado de BMC. Reintenta con espera; si persiste, escríbenos. |
502 / 503 | Servicio no disponible | Un servicio del que depende la operación (por ejemplo, el almacenamiento de documentos) no responde. Reintenta con espera. |
400, 404, 409 y 422: corrige la petición. Reintentar igual no cambia el resultado.401: comprueba que el token siga activo y vigente; si no, crea o rota otro (Autenticación).403: añade el permiso que indica required_permission al token (Permisos) o comprueba la lista de IPs.429: espera los segundos de Retry-After (Límites de uso).5xx: reintenta con espera creciente y un número máximo de intentos.