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íe la clave en la cabecera `X-B2B-API-Key` y asegúrese 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íe la clave en la cabecera `X-B2B-API-Key` y asegúrese de que coincida con el entorno (sandbox, staging o producción).
`invalid_api_key`	401	La clave API proporcionada no es válida	Envíe una clave válida en la cabecera `X-B2B-API-Key` y asegúrese de que coincida con el entorno (sandbox, staging o producción).
`expired_api_key`	401	La clave API proporcionada ha caducado	Envíe 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	Solicite 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 su tenant	Verifique el endpoint y el ID que está enviando.
`invalid_request_params`	400	JSON malformado, tipos incorrectos o estructura inesperada	Valide el payload antes de enviarlo.
`invalid_api_version` ¹	400	La versión de API `{api_version}` no es compatible	Valide el payload antes de enviarlo.
`missing_api_version` ¹	400	La versión de API no está especificada ni en la cabecera ni en IntegrationGroup	Valide 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	Cambie el subdominio por uno correcto. Use app.b2brouter o app-staging.b2brouter para la versión heredada (v2025-01-01). Use 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	Rellene los campos requeridos y reenvíe.
`parameter_inclusion`	422	El valor no está en el catálogo permitido (p. ej., un `scheme` inválido)	Compruebe los valores permitidos (consulte la Guía de Esquemas / listas) y corríjalo.
`parameter_taken`	422	Ya existe un valor único (p. ej., número de factura)	Use un nuevo valor o realice un GET primero para evitar duplicados.
`parameter_cannot_change`	422	Intento de editar un campo inmutable	Elimine el campo de la actualización o cree un nuevo recurso.
`conflict`	409	El estado actual del recurso rechaza la operación	Resuelva el conflicto de estado y vuelva a intentarlo.
(sin código)	429	Ha superado el límite de velocidad	Implemente retroceso exponencial, use caché y prefiera 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úrese de usar la clave correcta para su 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 pueda 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. Puede 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 sus 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: mantenga claves separadas por entorno y envíe siempre X-B2B-API-Key.
Limitación de velocidad: use retroceso exponencial, almacene en caché las respuestas y prefiera los webhooks frente al polling siempre que sea posible.
Vocabularios controlados: cuando un valor debe provenir de un catálogo (p. ej., scheme), consulte primero la API/guía de Esquemas.