The envelope
Status codes
The HTTP status tells you the class of failure; thecode tells you the specific one.
Handling failures
Branch oncode, never on message. Codes are stable identifiers; messages are prose we may reword to be clearer. An integration that string-matches messages will break on a copy edit.
A 404 does not always mean “never existed.” The API never confirms that another workspace’s resources exist, so a 404 on an id you believe you own can also mean the resource belongs to a different workspace. This is deliberate: it prevents anyone from probing ids to map out other tenants’ data.
Retry 429 and 500; fix everything else. On 429, honor the Retry-After header before retrying — see Rate limits for the windows. On 500, GET requests are safe to retry with backoff; for writes, confirm whether the operation took effect before re-issuing it. Statuses in the 400–422 range describe a problem with the request itself — retrying the same request will fail the same way, so correct it first (for validation errors, param points at the field to fix).
Example: a 404 in full
Requesting rows from a list id that does not exist in your workspace:Error code catalogue
Every code the API returns, grouped by area.doc_url in a live error response links to the matching section below.
UNAUTHORIZED
401 — The API token is missing, malformed, expired or revoked. Check that you are sending the key as the Basic-auth username with an empty password, and that the key has not been revoked in API Cockpit — see Authentication.
INSUFFICIENT_SCOPE
403 — This API token is not scoped for this endpoint. The key itself is valid; it was created without the scope this endpoint requires. Create a key with the right scopes, or use an unscoped key — see Scopes.
ENDPOINT_NOT_FOUND
404 — No endpoint matches this path and method. Check for typos in the path and confirm the HTTP method against the API reference; a POST to a GET-only path returns this code.
RATE_LIMITED
429 — You have exceeded the rate limit. Wait for the window to reset before retrying, honoring the Retry-After header — see Rate limits.
INVALID_REQUEST
400 — The request was malformed or failed validation. param identifies the offending field when there is one. Fix the request before retrying; the same payload will keep failing.
UNEXPECTED_ERROR
500 — An unexpected error occurred. Retry GET requests with backoff; for writes, verify state first. If it persists, contact support with the request_id.
INSUFFICIENT_CREDITS
402 or 422 — The workspace does not have enough credits for the operation. The request is rejected before any work is billed, so a failed request never consumes credits. Check your balance and see Credits.
LIST_NOT_FOUND
404 — No list with that id is visible to your workspace. Verify the id against GET /business/lists; an id belonging to another workspace also returns this code.
LIST_NAME_TAKEN
409 — A list with that name already exists in your workspace. Pick a different name, or add to the existing list instead of creating a new one.
COLUMN_NAME_TAKEN
409 — The list already has a column with that name. Column names are unique per list; rename the new column or update the existing one — see Custom columns.
SEARCH_FILTERS_INVALID
422 — The search filters could not be interpreted. Check filter keys and values against GET /business/prospects/filter-options, and see Build a list from search for working examples.
SAVED_SEARCH_NOT_FOUND
404 — No saved search with that id is visible to your workspace. List available saved searches with GET /business/saved-searches.
SAVED_SEARCH_INVALID
422 — The saved search exists but its stored filters cannot be run as-is. Recreate or fix the search in the app, then run it again.
EXCLUDE_COMPANY_LISTS_INVALID
422 — One or more ids in excludeCompanyLists do not resolve to company lists visible to your workspace. Check the ids and that each references a company list, not a contact list.
CONTACT_NOT_FOUND
404 — No contact with that id is visible to your workspace. Contacts belonging to another workspace also return this code.
EXPORT_NOT_FOUND
404 — No export job matching that id was found (it may have expired). Start a new export and poll the fresh job id — see Export a list.
CAMPAIGN_NOT_FOUND
404 — No campaign with that id is visible to your workspace. Campaigns belonging to another workspace also return this code.
CAMPAIGN_NOT_APPROVABLE
409 — The campaign is not in a state that can be approved — it may already be approved or otherwise past the approval step. Fetch the campaign to check its current state — see Campaigns.
CAMPAIGN_NOT_READY
422 — The campaign is still being prepared and cannot be acted on yet. Poll the campaign until it is ready, then retry — see Campaigns.
INVALID_CAMPAIGN_CHANNELS
422 — The channels value is not a valid channel combination for this campaign. Check the accepted values in the API reference.
LIST_INCOMPATIBLE_WITH_CHANNELS
422 — The list has no contacts reachable on the requested channels — it is empty, or no contact has an email address (or LinkedIn profile) for them. Enrich the list or choose channels its contacts can actually be reached on.
SEQUENCE_STEP_NOT_FOUND
404 — No sequence step with that id exists on this campaign. List the campaign’s steps with GET /business/campaigns/{campaignId}/steps to get valid step ids.
TEMPLATE_NOT_FOUND
404 — The templateId does not resolve to a template visible to your workspace. Check the id, or omit it to let the campaign generate copy without a template.
WRITING_STYLE_NOT_FOUND
404 — The writingStyleId does not resolve to a writing style visible to your workspace. Check the id against the styles configured in the app.
KNOWLEDGE_HUB_NOT_FOUND
404 — The knowledgeHubId does not resolve to a knowledge hub visible to your workspace. List available hubs with GET /business/knowledge-hubs — see Knowledge hubs.