Errors

For AI agents: the docs index is at /llms.txt, and every page is also served as markdown at its URL plus .md.

Every error from the API has the same JSON envelope. Branch on error.code, which is stable. The message is for people and can change.

The error envelope#

JSON

{
  "error": {
    "code": "invalid_input",
    "message": "prospects.0.country: Too big: expected string to have exactly 2 characters",
    "fix": "Correct the field named in the message and resend. Each product input schema is in the OpenAPI document. Nothing was charged.",
    "docs_url": "/docs/errors#invalid_input",
    "retryable": false,
    "request_id": "req_Qx7RtVw3ZbN1pEs9fKd2Lm"
  }
}

Field	Meaning
`code`	A stable identifier, one of the codes below.
`message`	What went wrong in this case.
`fix`	What to do about it.
`docs_url`	A relative path to the entry for this code on this page, such as `/docs/errors#invalid_input`. Open it on this site.
`retryable`	`true` when sending the same request again later can succeed.
`request_id`	Also sent as the `X-Request-Id` header. Quote it when you contact support.

Error codes#

Code	HTTP status	Retryable
`unauthorized`	401	No
`forbidden`	403	No
`insufficient_credits`	402	No
`plan_limit`	402	No
`subscription_required`	402	No
`rate_limited`	429	Yes
`invalid_input`	400	No
`unknown_product`	404	No
`method_not_allowed`	405	No
`payload_too_large`	413	No
`conflict`	409	No
`provider_unavailable`	503	Yes
`internal_error`	500	Yes

provider_unavailable is retryable by default, but the API sets retryable to false when the service is not configured. Always read the field in the response.

unauthorized#

HTTP 401. Retryable by default: no.

The API key is missing, malformed, revoked or unknown.

What to do: Send a valid key as Authorization: Bearer cm_live_.... If the key was revoked, ask the operator for a new one. See Authentication.

forbidden#

HTTP 403. Retryable by default: no.

The key is valid but may not do this. There are two causes: a read only key used on a request that changes data, and a resume of a campaign that ColdMeetings paused itself.

What to do: Use a key with write access for a change. Ask the operator for one if you only have a read-only key. A campaign that ColdMeetings paused itself is resumed only by an operator, after the cooldown. See Campaigns.

insufficient_credits#

HTTP 402. Retryable by default: no.

A prospect import needs more credits than the account has.

What to do: Import fewer prospects, or wait for the next monthly grant. Nothing was imported or charged.

plan_limit#

HTTP 402. Retryable by default: no.

The account is on a paid plan and has reached its limit of sending domains or mailboxes.

What to do: Move to a plan with higher limits. The limits are in Credits and billing. Nothing was created.

subscription_required#

HTTP 402. Retryable by default: no.

The account has no active plan, and creating a sending domain or a mailbox needs one. Nothing was created.

What to do: Start a checkout for a paid plan, then retry. See Credits and billing.

rate_limited#

HTTP 429. Retryable by default: yes.

The key made more requests than its bucket allows.

What to do: Wait the number of seconds in the Retry-After header, then retry. See Rate limits.

invalid_input#

HTTP 400. Retryable by default: no.

The request cannot be accepted as sent: the body is empty, is not JSON or fails validation, or a rule refused it. Rules include a sequence step without {{unsubscribe}} or {{sender_address}}, a campaign that is not a draft, a domain that is already registered, and a launch with blockers.

What to do: Read the message, which names the field or lists the problems, correct the request and resend. Nothing was created or charged.

unknown_product#

HTTP 404. Retryable by default: no.

No endpoint exists at this method and path, or the id you sent does not belong to this account. This code name comes from the shared API platform: in ColdMeetings it means "not found".

What to do: Check the path against the API reference, and check that the id came from this account.

method_not_allowed#

HTTP 405. Retryable by default: no.

The path exists but not for this HTTP method.

What to do: Use the method shown for that path in the API reference.

payload_too_large#

HTTP 413. Retryable by default: no.

The request body is over 256 KiB.

What to do: Send fewer items. Split a large prospect list into several imports of up to 500.

conflict#

HTTP 409. Retryable by default: no.

The request conflicts with the current state. A checkout is refused when the account already has a subscription, and a campaign resume is refused while the sending engine has not confirmed the pause or the plan's active campaigns are all in use.

What to do: For a checkout, keep the current plan; the operator can change or cancel it. For a resume, wait for the engine to confirm the pause or pause another active campaign, then retry.

provider_unavailable#

HTTP 503. Retryable by default: yes.

A step needs an outside service and it is not available. When retryable is false, the service is not configured on this server. When it is true, it failed for now.

What to do: If retryable is true, retry later with exponential backoff. If it is false, retrying will not help until the operator configures the service. Nothing is simulated and nothing was charged.

internal_error#

HTTP 500. Retryable by default: yes.

An unexpected error on our side.

What to do: Retry once after a short wait. If it fails again, email hello@coldmeetings.com with the request_id.