Error codes

`error.code`	HTTP	Typical cause	What to do
`unauthorized`	401	Missing/invalid API key, or key from a different environment	Send the key in header `X-B2B-API-Key` and make sure it matches the environment (sandbox, staging, or production).
`missing_api_key`	401	That API Key has not been provided in the header	Send the key in header `X-B2B-API-Key` and make sure it matches the environment (sandbox, staging, or production).
`invalid_api_key`	401	The provided API Key is not a valid one	Send a valid key in header `X-B2B-API-Key` and make sure it matches the environment (sandbox, staging, or production).
`expired_api_key`	401	The provided API Key has been expired	Send a valid and active key in header `X-B2B-API-Key`
`no_account_group`	403	Valid key but no group/permissions linked to it	Ask to enable/assign permissions for this key (staging accounts require a support request; sandbox permissions are automatic).
`resource_missing`	404	The resource ID doesn’t exist or is not accessible in your tenant	Recheck the endpoint and the ID you’re sending.
`invalid_request_params`	400	Malformed JSON, wrong types or unexpected structure	Validate the payload before sending.
`invalid_api_version` ¹	400	API Version `{api_version}` is not supported	Validate the payload before sending.
`missing_api_version` ¹	400	API Version is not specified neither in Header nor IntegrationGroup	Validate the payload before sending.
`api_version_subdomain_mismatch` ¹	400	The subdomain does not match with API Version specified in the header `X-B2B-API-Version` or the associated with the API Key	Change the subdomain to a correct one. Use app.b2brouter or app-staging.b2brouter for legacy version (v2025-01-01). Use api.b2brouter or api-staging.b2brouter for all other versions starting from v2025-10-13.
`parameter_blank`, `parameter_empty`	422	Required fields missing/blank	Populate required fields and resend.
`parameter_inclusion`	422	Value not in the permitted catalogue (e.g., an invalid `scheme`)	Check allowed values (see Schemes Guide / lists) and correct.
`parameter_taken`	422	A unique value already exists (e.g., invoice number)	Use a new value or GET first to avoid duplicates.
`parameter_cannot_change`	422	Attempt to edit an immutable field	Remove the field from the update or create a new resource.
`conflict`	409	Current resource state rejects the operation	Resolve the state conflict, then retry.
(no code)	429	You exceeded the rate limit	Implement exponential backoff, cache, and prefer webhooks over polling.

Fast examples

1) 401 Unauthorized (wrong/missing API key or wrong environment)

Example Request:

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'

Sample Response:

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

Make sure you’re using the right key for your environment (sandbox test_…, staging, or production) and sending it in X-B2B-API-Key.

2) 404 Not Found (Resource doesn’t exist or is not accessible)

Example Request:

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'

Sample Response:

{
  "error": "Not found"
}

3) 422 Unprocessable Entity (validation errors)

Example Request:

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

Sample Response:

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

Validation failures return HTTP 422 (Unprocessable Entity) with field-level error details, so you can fix the input and resend the request if necessary.

Request tracing

Every logged API response includes the header X-B2B-API-Request-Id with the unique identifier of the stored request log. You can use this value to:

Correlate a response with its server-side log entry.
Reference it in support tickets for faster investigation.
Include it in your own application logs for end-to-end tracing.

Error responses also include a request_log_url field in the JSON body that links directly to the request log.

Error-handling best practices

Authentication: keep separate keys per environment and always send X-B2B-API-Key.
Rate limiting: use exponential backoff, cache responses, and prefer webhooks to polling when possible.
Controlled vocabularies: when a value must come from a catalogue (e.g., scheme), check the Schemes API/guide first.