Códigos de error

`error.code`	HTTP	Causa habitual	Qué hacer
`unauthorized`	401	Clave API ausente/inválida, o clave de un entorno diferente	Envía la clave en la cabecera `X-B2B-API-Key` y asegúrate de que coincida con el entorno (sandbox, staging o producción).
`missing_api_key`	401	No se ha proporcionado esa clave API en la cabecera	Envía la clave en la cabecera `X-B2B-API-Key` y asegúrate de que coincida con el entorno (sandbox, staging o producción).
`invalid_api_key`	401	La clave API proporcionada no es válida	Envía una clave válida en la cabecera `X-B2B-API-Key` y asegúrate de que coincida con el entorno (sandbox, staging o producción).
`expired_api_key`	401	La clave API proporcionada ha caducado	Envía una clave válida y activa en la cabecera `X-B2B-API-Key`.
`no_account_group`	403	Clave válida pero sin grupo/permisos vinculados a ella	Solicita habilitar/asignar permisos para esta clave (las cuentas de staging requieren una solicitud de soporte; los permisos de sandbox son automáticos).
`resource_missing`	404	El ID del recurso no existe o no es accesible en tu tenant	Verifica el endpoint y el ID que estás enviando.
`invalid_request_params`	400	JSON malformado, tipos incorrectos o estructura inesperada	Valida el payload antes de enviarlo.
`invalid_api_version` ¹	400	La versión de API `{api_version}` no es compatible	Valida el payload antes de enviarlo.
`missing_api_version` ¹	400	La versión de API no está especificada ni en la cabecera ni en IntegrationGroup	Valida el payload antes de enviarlo.
`api_version_subdomain_mismatch` ¹	400	El subdominio no coincide con la versión de API especificada en la cabecera `X-B2B-API-Version` o la asociada a la clave API	Cambia el subdominio por uno correcto. Usa app.b2brouter o app-staging.b2brouter para la versión heredada (v2025-01-01). Usa api.b2brouter o api-staging.b2brouter para todas las demás versiones a partir de v2025-10-13.
`parameter_blank`, `parameter_empty`	422	Campos requeridos ausentes o en blanco	Rellena los campos requeridos y reenvía.
`parameter_inclusion`	422	El valor no está en el catálogo permitido (p. ej., un `scheme` inválido)	Comprueba los valores permitidos (consulta la Guía de Esquemas / listas) y corrígelo.
`parameter_taken`	422	Ya existe un valor único (p. ej., número de factura)	Usa un nuevo valor o realiza un GET primero para evitar duplicados.
`parameter_cannot_change`	422	Intento de editar un campo inmutable	Elimina el campo de la actualización o crea un nuevo recurso.
`conflict`	409	El estado actual del recurso rechaza la operación	Resuelve el conflicto de estado y vuelve a intentarlo.
(sin código)	429	Has superado el límite de velocidad	Implementa retroceso exponencial, usa caché y prefiere los webhooks frente al polling.

Ejemplos rápidos

1) 401 No autorizado (clave API incorrecta/ausente o entorno incorrecto)

Ejemplo de solicitud:

curl --request GET \
  --url 'https://api-staging.b2brouter.net/accounts?offset=0&limit=25' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

Respuesta de ejemplo:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API Key provided, or the API key might not have the necessary permissions for this action.",
    "type": "invalid_request_error"
  }
}

Asegúrate de usar la clave correcta para tu entorno (sandbox test_…, staging o producción) y enviarla en X-B2B-API-Key.

2) 404 No encontrado (el recurso no existe o no es accesible)

Ejemplo de solicitud:

curl --request GET \
  --url https://api-staging.b2brouter.net/directory/es/ES1234567890 \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

Respuesta de ejemplo:

{
  "error": "Not found"
}

3) 422 Entidad no procesable (errores de validación)

Ejemplo de solicitud:

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/transports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json'
'

Respuesta de ejemplo:

{
  "error": {
    "code": "parameter_taken",
    "message": "Transport type code has already been taken and Peppol Endpoint ID has already been taken",
    "param": "transport_type_code",
    "request_log_url": "https://api-staging.b2brouter.net/api_requests/123456",
    "type": "invalid_request_error"
  }
}

Los errores de validación devuelven HTTP 422 (Entidad no procesable) con detalles de error a nivel de campo, para que puedas corregir la entrada y reenviar la solicitud si es necesario.

Trazabilidad de solicitudes

Cada respuesta de API registrada incluye la cabecera X-B2B-API-Request-Id con el identificador único del registro de solicitud almacenado. Puedes usar este valor para:

Correlacionar una respuesta con su entrada de registro en el servidor.
Referenciarlo en tickets de soporte para una investigación más rápida.
Incluirlo en tus propios registros de aplicación para trazabilidad de extremo a extremo.

Las respuestas de error también incluyen un campo request_log_url en el cuerpo JSON que enlaza directamente al registro de la solicitud.

Buenas prácticas para el manejo de errores

Autenticación: mantén claves separadas por entorno y envía siempre X-B2B-API-Key.
Limitación de velocidad: usa retroceso exponencial, almacena en caché las respuestas y prefiere los webhooks frente al polling siempre que sea posible.
Vocabularios controlados: cuando un valor debe provenir de un catálogo (p. ej., scheme), consulta primero la API/guía de Esquemas.