Codis d'error

`error.code`	HTTP	Causa típica	Què cal fer
`unauthorized`	401	Clau d’API absent/no vàlida, o clau d’un entorn diferent	Envia la clau a la capçalera `X-B2B-API-Key` i assegura’t que coincideix amb l’entorn (sandbox, staging o producció).
`missing_api_key`	401	Aquesta clau d’API no s’ha proporcionat a la capçalera	Envia la clau a la capçalera `X-B2B-API-Key` i assegura’t que coincideix amb l’entorn (sandbox, staging o producció).
`invalid_api_key`	401	La clau d’API proporcionada no és vàlida	Envia una clau vàlida a la capçalera `X-B2B-API-Key` i assegura’t que coincideix amb l’entorn (sandbox, staging o producció).
`expired_api_key`	401	La clau d’API proporcionada ha caducat	Envia una clau vàlida i activa a la capçalera `X-B2B-API-Key`
`no_account_group`	403	Clau vàlida però sense grup/permisos vinculats	Demana que s’habilitin/assignin permisos per a aquesta clau (els comptes de staging requereixen una sol·licitud de suport; els permisos de sandbox són automàtics).
`resource_missing`	404	L’ID del recurs no existeix o no és accessible al teu tenant	Revisa l’endpoint i l’ID que estàs enviant.
`invalid_request_params`	400	JSON mal format, tipus incorrectes o estructura inesperada	Valida el payload abans d’enviar-lo.
`invalid_api_version` ¹	400	La versió d’API `{api_version}` no és compatible	Valida el payload abans d’enviar-lo.
`missing_api_version` ¹	400	La versió de l’API no s’especifica ni a la capçalera ni al IntegrationGroup	Valida el payload abans d’enviar-lo.
`api_version_subdomain_mismatch` ¹	400	El subdomini no coincideix amb la versió d’API especificada a la capçalera `X-B2B-API-Version` o la associada a la clau d’API	Canvia el subdomini a un de correcte. Usa app.b2brouter o app-staging.b2brouter per a la versió legacy (v2025-01-01). Usa api.b2brouter o api-staging.b2brouter per a totes les versions des de v2025-10-13.
`parameter_blank`, `parameter_empty`	422	Camps requerits absents/en blanc	Omple els camps requerits i torna a enviar.
`parameter_inclusion`	422	El valor no es troba al catàleg permès (per exemple, un `scheme` no vàlid)	Comprova els valors permesos (consulta la Guia d’Esquemes / llistes) i corregeix.
`parameter_taken`	422	Un valor únic ja existeix (per exemple, número de factura)	Usa un valor nou o fes un GET primer per evitar duplicats.
`parameter_cannot_change`	422	Intent d’editar un camp immutable	Elimina el camp de l’actualització o crea un nou recurs.
`conflict`	409	L’estat actual del recurs rebutja l’operació	Resol el conflicte d’estat i torna a intentar-ho.
(sense codi)	429	Has superat el límit de velocitat	Implementa backoff exponencial, fes cache i prefereix webhooks en lloc de polling.

Exemples ràpids

1) 401 Unauthorized (clau d’API incorrecta/absent o entorn incorrecte)

Exemple de petició:

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'

Resposta d’exemple:

{
  "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"
  }
}

Assegura’t d’utilitzar la clau correcta per al teu entorn (sandbox test_…, staging o producció) i d’enviar-la a X-B2B-API-Key.

2) 404 Not Found (El recurs no existeix o no és accessible)

Exemple de petició:

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'

Resposta d’exemple:

{
  "error": "Not found"
}

3) 422 Unprocessable Entity (errors de validació)

Exemple de petició:

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'
'

Resposta d’exemple:

{
  "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"
  }
}

Els errors de validació retornen HTTP 422 (Unprocessable Entity) amb detalls d’errors a nivell de camp, de manera que pots corregir l’entrada i tornar a enviar la petició si és necessari.

Traçabilitat de peticions

Cada resposta d’API registrada inclou la capçalera X-B2B-API-Request-Id amb l’identificador únic del log de la petició emmagatzemada. Pots utilitzar aquest valor per:

Correlacionar una resposta amb la seva entrada de log del servidor.
Referenciar-lo en tiquets de suport per a una investigació més ràpida.
Incloure’l als teus propis logs d’aplicació per a la traçabilitat d’extrem a extrem.

Les respostes d’error també inclouen un camp request_log_url al cos JSON que enllaça directament al log de la petició.

Bones pràctiques de gestió d’errors

Autenticació: mantén claus separades per entorn i sempre envia X-B2B-API-Key.
Limitació de velocitat: usa backoff exponencial, fes cache de les respostes i prefereix webhooks al polling sempre que sigui possible.
Vocabularis controlats: quan un valor ha de provenir d’un catàleg (per exemple, scheme), comprova primer l’API/guia d’Esquemes.