Error codes

Quick table (code → HTTP → action)

`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 (staging vs 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 (staging vs 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 (staging vs 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 often requires a support request).
`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.

¹ Available from version 2025-10-13

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 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' \
     --data '
{
  "transport": {
    "code": "peppol",
    "enabled": true,
    "reception": true,
    "pin_scheme": 208,
    "pin_value": "0123456789"
  }
}
'

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.