Errors
Every error code the API returns, what it means, and whether to retry. Each error's docs link points here.
Every error has this shape. docs links to the code's section on this
page; field names the field at fault, when there is one. Every response
carries an x-request-id header: quote it to support.
{
"error": {
"code": "domain_not_verified",
"message": "daringaming.com is not verified in this workspace.",
"docs": "https://charchy.krd/docs/errors#domain_not_verified"
}
}Match on code, never on message: messages can change, codes never do.
All codes
| HTTP | Code | Retry? |
|---|---|---|
| 400 | invalid_json | No |
| 400 | validation_error | No |
| 400 | invalid_idempotency_key | No |
| 401 | missing_api_key | No |
| 401 | invalid_api_key | No |
| 402 | insufficient_balance | No |
| 403 | restricted_api_key | No |
| 403 | domain_not_verified | No |
| 403 | sender_not_allowed | No |
| 403 | not_approved | No |
| 403 | sending_paused | No |
| 404 | not_found | No |
| 409 | idempotency_conflict | No |
| 409 | idempotency_in_flight | Yes, after Retry-After |
| 413 | payload_too_large | No |
| 422 | invalid_attachment | No |
| 422 | too_many_recipients | No |
| 422 | schedule_out_of_range | No |
| 429 | rate_limit_exceeded | Yes, after Retry-After |
| 429 | daily_limit_reached | Yes, after Retry-After |
| 500 | internal_error | Yes, with backoff |
| 503 | sending_unavailable | Yes, after Retry-After |
Retrying is only safe with an Idempotency-Key — send
one on every request.
400 Bad Request
invalid_json
The body isn't valid JSON, or isn't a JSON object. Send
Content-Type: application/json and serialise the body once — a JSON string
inside a JSON string is the usual cause.
validation_error
A field is missing or wrong. field names it; message says what's
wrong — an address that isn't one, an unknown field, a reserved header, a
line break in a subject, a scheduled_at without a time zone, an
expires_at already past. In a batch, invalid emails answer
422, and items lists every problem by the email's index, each with its
own code.
Also returned for well-formed requests that can't be done: rescheduling an
email that isn't scheduled, canceling one that has already left, uploading
an image that isn't PNG, JPEG, GIF or WebP, or a 201st hosted image.
{ "error": { "code": "validation_error", "field": "to", "message": "\"ara@\" is not an email address.", "docs": "https://charchy.krd/docs/errors#validation_error" } }invalid_idempotency_key
The Idempotency-Key header is empty, longer than 256 characters, or has
anything other than printable ASCII — a line break, a tab, a Kurdish or
Arabic letter. Nothing was sent. Use a short key made from the event, like
password-reset/7f1c2a. See Idempotency.
401 Unauthorized
missing_api_key
No Authorization header at all. Send Authorization: Bearer <key>.
invalid_api_key
The key is unknown, revoked (effective at once), not shaped like a Charchy
Send key (or not sent as Bearer <key>), or its workspace no longer has
Charchy Send. Check you're reading the right environment variable and that it
holds the whole key.
402 Payment Required
insufficient_balance
Your plan's emails for this term and your credits don't cover this
request — counted per recipient, all or nothing. Buy credits or renew your
plan in Usage & billing, then send again with the same Idempotency-Key
(a refused request isn't remembered under it).
Don't retry automatically — nothing changes until someone pays. Alert a
person instead. A balance.low webhook at 80% warns
you first.
403 Forbidden
restricted_api_key
The key isn't allowed to do this:
- a sending-only key read, listed, rescheduled or canceled an email, or
uploaded an image (it may send and call
GET /v1/usage); - a key locked to one domain sent from another;
- a locked key's domain was removed from the workspace, so it can't send at all — make a new key.
Use a key with full permission, or the right domain.
domain_not_verified
The from domain is added to this workspace but not verified — its DNS
records aren't published, or verification gave up. Open Domains in the
dashboard; see Domains and DNS. A
test key may send from any domain meanwhile.
sender_not_allowed
The from domain isn't one of this workspace's sending domains — never
added here, or a typo. Only the exact domain counts: add a subdomain on its
own. Add and verify it under Domains.
not_approved
Your workspace isn't approved for live sending yet, so a live key sends
only to your own team's addresses (up to 50 recipients a day). field names
the first address that isn't one. Use a
test key or a magic address, or contact us to finish
approval.
sending_paused
Live sending is paused for your workspace — usually because bounces or spam
complaints rose too high, volume jumped far above normal, or mail looked like
marketing (why, automatic pauses).
Your owners and admins got an email with the reason, and an account.paused
webhook fired. Test keys keep working.
Live mail accepted before the pause is held: it goes out when sending
resumes, unless its expires_at passes or it waits 3 days past its due time
first (held mail). Retrying doesn't help;
sending resumes once we've reviewed it with you.
404 Not Found
not_found
No email with this id in your workspace — including ids from another
workspace, anything not shaped like an email id (em_ and 24 letters and
digits), and emails older than 30 days.
409 Conflict
idempotency_conflict
You reused an Idempotency-Key from the last 24 hours with a different
body, or on the other send endpoint (/v1/emails and /v1/emails/batch
share keys). Nothing was sent. Make the key from the event that causes the
email, so different emails never share one. See Idempotency.
idempotency_in_flight
A request with the same Idempotency-Key is still being processed — this
happens while a request with attachments or a large body uploads. Wait
Retry-After seconds and retry with the same key: you get the first
request's answer.
413 Content Too Large
payload_too_large
The request body is over 5 MB, html or text is over 512 KB, or a hosted
image is over 2 MB. Put large files behind a download link, and big images in
hosted images.
422 Unprocessable Content
invalid_attachment
An attachment is invalid: filename or content_type is missing,
content isn't valid base64 or is an empty file, there are more than 3 files
or more than 3 MB together, its type is blocked (executables and scripts),
or a content_id is used twice. See
attachments. (Attachments in a
batch answer validation_error.)
too_many_recipients
to, cc and bcc together have more than 50 addresses, after duplicates
are dropped. Send one email per person instead.
schedule_out_of_range
scheduled_at is more than 30 days ahead, when sending or when
rescheduling. See Scheduling.
429 Too Many Requests
rate_limit_exceeded
More than 10 requests a second from your workspace, all keys together
(bursts of 20 are allowed). Wait Retry-After seconds and retry. Sending
many at once? Use batch. See Rate limits.
daily_limit_reached
This request would take your workspace past its daily cap — or, while your
sending is healthy, past twice it (the surge allowance) — counted per
recipient over a rolling 24 hours. Nothing was sent. Also returned when test
keys and magic addresses pass their 1,000 a day, and when a live key passes
50 a day before approval. Retry-After says when there is room. Caps grow
with your plan and sending history — see
Rate limits and quotas.
500 and 503
internal_error
Something broke on our side. Retry with backoff and the same
Idempotency-Key. If it persists, write to support@charchy.krd with the time
and the email's details.
sending_unavailable
Live sending is halted on our side, for every workspace, for 10 minutes or
more. Your request was not accepted or charged; wait Retry-After seconds
and retry with the same Idempotency-Key. Test keys keep working. Live mail
accepted before the halt is held and goes out when sending comes back.