API error codes
Every Outbound API error code with HTTP status, meaning and solution, so your integration responds correctly.
If the Outbound API rejects a request, it responds with success: false, a fixed code in error and an explanation in message. Your integration branches on error, not on the text: the codes stay stable, the texts may change.
{
"success": false,
"error": "invalid_to_number",
"message": "toNumber must be an international number in E.164 format …"
}
Overview
| Status | Meaning | Try again? |
|---|---|---|
| 400 | The request is incomplete or invalid | only after correcting it |
| 401 | Authentication is missing or invalid | only after correcting it |
| 402 | A subscription or payment is missing for this route | only after payment |
| 403 | This action isn't enabled yet for your account or the number | only once enabled |
| 409 | A request with the same Idempotency-Key is still running | yes, after Retry-After |
| 422 | The request doesn't match the configuration | only after correcting it |
| 429 | Limit reached | yes, after Retry-After |
| 500, 503 | Error on our side | yes, after a pause and with the same Idempotency-Key |
400: Invalid request
invalid_to_number
The destination number isn't in E.164 format. Write it with a plus sign and country code, such as +491701234567. The API rejects national formats like 0170 … because the country can't be reliably determined from them.
invalid_from_number
The sender number isn't in E.164 format. Write it like the destination number, with a plus sign and country code.
outbound_number_required
fromNumber is missing. Specify your sender number: an imported number or one connected via SIP, with an agent assigned to it.
platform_number_inbound_only
The sender number is a number purchased from bhomy. These numbers only receive calls. Import your own number or connect it via SIP.
invalid_idempotency_key
The Idempotency-Key header is empty, longer than 255 characters or contains characters outside ASCII. Use a UUID, for example.
validation_error
The sender number couldn't be checked just now. Try again after a pause.
If the body is missing or isn't valid JSON, the API also responds with 400, in that case with an explanation in error, such as "Missing required field: toNumber".
401: Authentication
For 401, the reason is in code:
code | Solution |
|---|---|
auth.missing_header | Send the Authorization: Bearer … header |
auth.invalid_type | The header starts with Bearer followed by a space |
auth.invalid_key | The key doesn't exist. Check it for spaces and line breaks |
auth.key_revoked | The key is deactivated. Reactivate it under API Key or use another one |
More on this under Problems with API keys.
402: Payment
imported_number_subscription
Calls from an imported number need an active subscription with no open invoice. Settle open invoices under Billing.
403: Not enabled yet
identity_not_verified
Via the API, bhomy only calls once your identity is verified. The response contains verify_url, the link to the Identity card under Billing. You only do the check once, see Outbound calls.
sender_not_verified
The sender number isn't confirmed for outbound calls yet. Confirm it with the verification call in its settings under Phone Number.
outbound_disabled
Outbound calls aren't set up for this SIP number. Connect it with your provider's termination address and credentials.
409: Still running
idempotency_request_in_progress
A request with the same Idempotency-Key is being processed right now. Wait the number of seconds in Retry-After and send the same request again. You then get the response to the first one.
422: Doesn't match the configuration
idempotency_key_reused
This Idempotency-Key already belongs to a different request. Use a new key for every new call.
no_assistant_mapped
No agent is assigned to the sender number. Assign an agent to it under Phone Number.
imported_number_destination
An imported number calls German landline and mobile numbers. For other destinations, use a SIP number through your own provider.
429: Limit reached
rate_limit_exceeded
More than 60 requests in 60 seconds. limit_scope names the limit: per IP address or per API key. Wait the number of seconds in Retry-After and spread out your requests.
concurrent_limit_reached
All lines are busy. With limit_scope: "account", it's the concurrent calls of your plan, and the response then states current and limit. With limit_scope: "platform", bhomy is briefly keeping lines free for inbound calls. In both cases, wait the number of seconds in Retry-After.
500 and 503: Error on our side
outbound_not_configured
Outbound calls aren't set up on our side right now. Contact support.
outbound_unavailable
The outbound call service is temporarily unavailable. Try again after a few minutes.
dispatch_failed
The agent couldn't be sent off. Try again with the same Idempotency-Key, so that no duplicate call is created.
internal_error
An unexpected error. Try again. If the error persists, write to us.
With these errors, the response often contains error_id. Send it to us, see Report a problem. It lets us find the process straight away.
When the request was accepted but no conversation took place
A 202 response means the request has been accepted. What happens next appears as a result on the call in the call history, such as No answer, Voicemail or Blocked if your account was blocked. Campaigns explains the results.
Was this page helpful?