Charchy Senddocs

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

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.

On this page