Koltrix logoKoltrixDocs
Reference

Errors

Errors from https://api.koltrix.com/api/v2 are JSON with an error string, whatever went wrong (a missing path and a request that is too large included):

{ "error": "missing permission: send" }

The error text is written for a person and may change wording. Decide what to do from the HTTP status, and for 429 from the code field (see below). Successful responses use 200, 201 (created), 202 (accepted for sending) and 204 (deleted, empty body).

Should I retry?

StatusRetry?
400, 401, 403, 404No. Fix the request, key or data first.
409Yes, after a short wait, with the same Idempotency-Key.
429 without codeYes, after Retry-After seconds.
429 with "code": "quota_exceeded"Not until resets_at. Tell a person.
402No. Upgrade or remove contacts first, or (workspace_read_only) choose or fix a plan.
413No. Make the request smaller.
500Yes, with backoff. For POST /api/v2/emails, retry with the same Idempotency-Key and nothing is sent twice.
503Yes, with the same Idempotency-Key.

A good default: retry 409, 429 (rate limit), 500 and 503 with exponential backoff starting at one second, give up after a few minutes, and log everything else for a person to look at.

400 Bad Request

The request can't be processed as sent.

errorEndpointFix
invalid bodyAny with a bodySend valid JSON with Content-Type: application/json, and check field types: to, cc and bcc are arrays.
from, to, subject are requiredPOST /emailsInclude all three, non-empty.
from address is not a valid emailPOST /emailsfrom must contain an address, like [email protected] or Acme <[email protected]>.
subject and body_html requiredPOST /lists/:id/broadcastInclude both.
from_address required (and list has none configured)POST /lists/:id/broadcastPass from_address, or set one on the list.
csv body requiredPOST /lists/:id/subscribers/importSend {"csv": "…"} with the file's contents.
name is requiredPOST /lists, POST /sequencesInclude a non-empty name.
subject is requiredPOST /sequences/:id/stepsInclude a non-empty subject.
invalid email: …POST /lists/:id/subscribersThe email isn't a valid address.
invalid address in to: "…", to contains an empty addressPOST /emailsA recipient in to, cc or bcc isn't an address. The text names the list and the address.
too many recipients: at most 1000 addresses across to, cc and bccPOST /emailsSplit the send.
subject is longer than 988 charactersPOST /emails, POST /sequences/:id/steps, POST /lists/:id/broadcastShorten the subject. (Line breaks in a subject are replaced with spaces, not refused.)
from_address must not contain line breaks, from_address is not a valid email address (also from_name, reply_to, name)POST /lists, PATCH /lists/:idFix the field.
Idempotency-Key is longer than 255 charactersPOST /emailsUse a shorter key.
list_id is required, trigger must be "subscribe"POST /sequencesName the list the sequence belongs to.
position must be 0 or more, delay_hours must be between 0 and 8760POST /sequences/:id/steps
status must be pending, active or unsubscribedGET /lists/:id/subscribers

401 Unauthorized

The API key is missing or not accepted. See Authentication.

errorFix
missing Bearer tokenSend Authorization: Bearer kx_….
invalid api key formatThe token must start with kx_.
invalid or revoked api keyThe key doesn't exist or was revoked. Create a new one.

403 Forbidden

The key is valid but may not do this.

errorFix
missing permission: send (or read, newsletter)Use a key with that scope. Which scope each endpoint needs.
This workspace is suspended or scheduled for deletion, so its API keys cannot be used. … (with "code": "workspace_unavailable")Contact [email protected]. The key is not revoked; it is not allowed to act while the workspace is.
from address '…' is not registered for this account. The domain is verified — add this exact address in Dashboard → Domains.Add the address under Settings → Domains & addresses → your domain → Add address.
from address '…' is not registered for this account. Add and verify the domain in Dashboard → Domains first, then add the mailbox.Verify the domain first, then add the address.

404 Not Found

errorMeaning
message not foundNo message with this id in this workspace. A message that is still queued is found, with "status": "queued".
list not foundNo list with this id in this workspace, or the id isn't a valid id. Also returned by endpoints that take a list (adding or importing subscribers, a broadcast, creating a sequence).
sequence not found, step not foundNo sequence or step with this id.
subscriber not foundNo subscriber with this id.
not foundThe path doesn't exist, or doesn't accept that method.

Deleting something that is already gone is not an error: it answers 204 again.

409 Conflict

a request with this Idempotency-Key is still in progress: a retry arrived while the first request with the same key was still running. Wait a moment and retry with the same key; you'll get the first request's response. See Retrying safely.

429 Too Many Requests

Two different things answer 429. Tell them apart by the code field.

Rate limit, no code:

{ "error": "rate limit exceeded — 60 requests per minute per API key" }

Wait for the number of seconds in the Retry-After header, then continue.

Send quota, "code": "quota_exceeded":

{
  "code": "quota_exceeded",
  "error": "You've hit today's API sending limit. It resets at midnight UTC, or upgrade to send more now.",
  "kind": "api_sends",
  "limit": 200,
  "used": 200,
  "window": "day",
  "resets_at": "2026-10-03T00:00:00Z",
  "upgrade_url": "https://app.koltrix.com/settings/billing"
}

Retrying won't help until resets_at. Surface it to a person. Details in Limits and quotas.

402 Payment Required

POST /lists/:id/subscribers and POST /lists/:id/subscribers/import answer 402 with the quota body and "kind": "contacts" when adding would pass your plan's contacts allowance. Retrying won't help until you upgrade or remove contacts.

POST /api/v2/emails answers 402 with "code": "workspace_read_only" when the workspace is read-only: the trial ended, a payment failed and the grace period ran out, or the subscription ended.

{
  "code": "workspace_read_only",
  "error": "Your trial has ended. Your mail is safe and keeps arriving — choose a plan to read everything and start sending again.",
  "reason": "trial_expired",
  "upgrade_url": "https://app.koltrix.com/settings/billing"
}

reason is trial_expired, past_due or canceled. Nothing is lost and reading still works. Retrying won't help until someone picks or fixes a plan in Settings → Billing; surface it to a person. The SMTP relay answers the same state with a temporary 450 4.7.0, so your mail server queues the message and retries.

413 Request Entity Too Large

{"error": "request body too large (the limit is 25 MB)"}. Don't retry the same request.

500 Internal Server Error

Something failed on Koltrix's side. The error text is a fixed, generic sentence (internal error, please retry, could not load message, could not verify the from address, please retry); the cause is in Koltrix's logs, not in the response. Retry with backoff; if it keeps happening, email [email protected] with the time and the endpoint.

POST /api/v2/emails releases its Idempotency-Key when it fails before the message is queued, so retrying with the same key is safe and sends at most one message.

503 Service Unavailable

idempotency store unavailable, please retry: Koltrix couldn't check the Idempotency-Key, so it sent nothing rather than risk sending twice. Retry with the same key.

SMTP relay

The SMTP relay answers with SMTP reply codes, not HTTP statuses. They are listed in SMTP relay → Reply codes.