Errors - outbound.dev

Every refusal uses the same JSON envelope and an HTTP status code that says what kind of failure it is. There is one shape to parse, so error handling is one code path.

{
  "error": {
    "code": "insufficient_balance",
    "message": "Your balance cannot cover this call. Add funds and try again.",
    "doc_url": "https://docs.outbound.dev/errors#insufficient_balance",
    "request_id": "req_6a1f0c2b9d4e8a7f3c5b2e10"
  }
}

Field	Description
`code`	Stable and machine-readable. Codes never change meaning, so branch on `code`.
`message`	A human-readable explanation, for logs. It may be reworded at any time: never match on it.
`param`	The request field the error is about, when there is one, such as `limit` or `filters.job_title_levels`.
`doc_url`	The code’s entry on this page.
`request_id`	The request’s id, also in the `X-Request-Id` header. Quote it when you write to us.

Status codes

Status	Meaning
`200`, `201`, `202`, `204`	Success. `202` means the answer is not ready yet: see counts.
`400`	The request could not be read.
`401`	The API key is missing, invalid, revoked or expired.
`402`	Your balance, or the key’s daily cap, cannot cover the call. Nothing ran.
`403`	The key’s scope does not allow the call, or its organization is closed.
`404`	No such resource for your organization.
`409`	The request conflicts with what exists.
`413`, `415`	The body is too large, or not JSON.
`422`	A field, filter or cursor is not valid. `param` names it.
`429`	Too many calls. The body is empty: wait the seconds in `Retry-After`. See Rate limits.
`5xx`	Something failed on our side. The body is empty and nothing was charged. Retry with backoff, and quote `X-Request-Id` if it persists.

Error codes

Keys and scope

api_key_missing

401. Send your API key in the Authorization header, as Bearer and then the key.

api_key_invalid

401. The key is malformed, its checksum is wrong, or no such key exists. Check that it was copied in full.

api_key_revoked

401. The key was revoked. Create a new one in the console.

api_key_expired

401. The key has expired. Create a new one in the console.

api_key_unusable

401. The key was revoked or expired while the call was being made. Create a new one in the console.

org_closed

403. The key’s organization is closed.

insufficient_scope

403. The key’s scope does not allow this call. The message names the scope it needs when it is not a product. See Scopes.

Requests

validation_failed

422. A field is missing, of the wrong type or out of range. param names it and message says what is wrong.

malformed_json

400. The request body is not valid JSON.

payload_too_large

413. The request body is too large.

unsupported_media_type

415. Send the request body as JSON in UTF-8.

bad_request

400. The request could not be read. Check its path and body.

route_not_found

404. No endpoint matches this method and path.

Balance

insufficient_balance

402. Your available balance cannot cover the most this call can cost. Add funds in the console, or ask for a smaller page with limit. Nothing ran and nothing was charged.

key_daily_cap_reached

402. This call would take the key past its daily spending cap. Caps reset at midnight UTC. Nothing ran.

Search

search_filters_invalid

422. A filter is not valid. param names it, such as filters.job_title_levels. Take filter names and values from GET /v1/people/filters or GET /v1/companies/filters.

filter_value_unresolved

422. A filter value, such as a place or a company, matches nothing that can be searched.

city_filter_unresolved

422. A city in the filters could not be found. Take place names from the autocomplete endpoints.

query_filters_invalid

422. The query could not be turned into a search. Rephrase it, or send filters instead.

invalid_cursor

422. The cursor is not one this API issued. Pass the nextCursor of the page before, or start again without a cursor.

search_changed

422. The search changed since this cursor was issued. Send the filters of the first page with the cursor, or start again without it.

company_identifier_invalid

422. Name the company by its name, website domain or LinkedIn company page.

Saved searches

saved_search_not_found

404. No saved search with this id belongs to your organization.

saved_search_name_ambiguous

409. More than one saved search has this title. Run it by its id instead.

saved_search_type_mismatch

422. This saved search is for the other kind of search: run a company one with POST /v1/companies/search and savedSearchId.

saved_search_invalid

422. This saved search can no longer be run. Update its filters.

saved_search_filters_unsupported

422. Some of these filters cannot be kept in a saved search.

Usage, requests and jobs

invalid_date_range

422. Dates must be YYYY-MM-DD, with from on or before to.

date_range_too_long

422. Ask for at most 90 days at a time.

request_log_not_found

404. No request with this id was made by your organization in the last 30 days. A key without full access sees only its own requests.

job_not_found

404. No job with this id was started by your organization.