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?
| Status | Retry? |
|---|---|
400, 401, 403, 404 | No. Fix the request, key or data first. |
409 | Yes, after a short wait, with the same Idempotency-Key. |
429 without code | Yes, after Retry-After seconds. |
429 with "code": "quota_exceeded" | Not until resets_at. Tell a person. |
402 | No. Upgrade or remove contacts first, or (workspace_read_only) choose or fix a plan. |
413 | No. Make the request smaller. |
500 | Yes, with backoff. For POST /api/v2/emails, retry with the same Idempotency-Key and nothing is sent twice. |
503 | Yes, 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.
error | Endpoint | Fix |
|---|---|---|
invalid body | Any with a body | Send valid JSON with Content-Type: application/json, and check field types: to, cc and bcc are arrays. |
from, to, subject are required | POST /emails | Include all three, non-empty. |
from address is not a valid email | POST /emails | from must contain an address, like [email protected] or Acme <[email protected]>. |
subject and body_html required | POST /lists/:id/broadcast | Include both. |
from_address required (and list has none configured) | POST /lists/:id/broadcast | Pass from_address, or set one on the list. |
csv body required | POST /lists/:id/subscribers/import | Send {"csv": "…"} with the file's contents. |
name is required | POST /lists, POST /sequences | Include a non-empty name. |
subject is required | POST /sequences/:id/steps | Include a non-empty subject. |
invalid email: … | POST /lists/:id/subscribers | The email isn't a valid address. |
invalid address in to: "…", to contains an empty address | POST /emails | A 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 bcc | POST /emails | Split the send. |
subject is longer than 988 characters | POST /emails, POST /sequences/:id/steps, POST /lists/:id/broadcast | Shorten 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/:id | Fix the field. |
Idempotency-Key is longer than 255 characters | POST /emails | Use a shorter key. |
list_id is required, trigger must be "subscribe" | POST /sequences | Name the list the sequence belongs to. |
position must be 0 or more, delay_hours must be between 0 and 8760 | POST /sequences/:id/steps | |
status must be pending, active or unsubscribed | GET /lists/:id/subscribers |
401 Unauthorized
The API key is missing or not accepted. See Authentication.
error | Fix |
|---|---|
missing Bearer token | Send Authorization: Bearer kx_…. |
invalid api key format | The token must start with kx_. |
invalid or revoked api key | The key doesn't exist or was revoked. Create a new one. |
403 Forbidden
The key is valid but may not do this.
error | Fix |
|---|---|
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
error | Meaning |
|---|---|
message not found | No message with this id in this workspace. A message that is still queued is found, with "status": "queued". |
list not found | No 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 found | No sequence or step with this id. |
subscriber not found | No subscriber with this id. |
not found | The 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.