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).
`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.
`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://app-staging.b2brouter.net/accounts?offset=0&limit=25' \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
     --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://app-staging.b2brouter.net/api/v1/directory/es/ES1234567890.json \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
     --header 'accept: application/json'

Sample Response:

{
  "error": "Not found"
}

3) 422 Unprocessable Entity (validation errors)

Example Request:

curl --request POST \
     --url https://app-staging.b2brouter.net/accounts/{ACCOUNT_ID}/transports \
     --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
     --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://app-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.

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.