Errors - Kourio

Every error has the same shape:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Marketing email accepts a single recipient per message",
    "details": [{ "path": "to", "message": "…" }],
    "requestId": "bac1da95-c96e-4e1f-82b8-b9d7…"
  }
}

Quote the requestId. It is what lets us find your exact request in the logs in seconds, instead of searching by timestamp and address. Keep it when you log the failure on your side.

The ones you will see most

Code	What happened	What to do
`VALIDATION_ERROR`	The body failed the schema	Read `details`, which names the field
`DOMAIN_NOT_VERIFIED`	The `from` is not on a verified domain of yours	Publish the DNS and call `verify`
`QUOTA_EXCEEDED`	The monthly quota ran out	`Retry-After` says how many seconds until it resets
`MARKETING_SENDING_UNAVAILABLE`	Marketing is closed on this account	Talk to us
`SUPPRESSED_RECIPIENT`	The address is on the suppression list	Do not force it; look at why it got there

Retrying safely

Send Idempotency-Key on a send. If the response is lost in transit, repeating the call with the same key returns the original send instead of delivering the message twice.

curl -X POST https://kourio.app/v1/emails \
  -H "Authorization: Bearer $KOURIO_API_KEY" \
  -H "Idempotency-Key: order-A-10428-confirmation" \
  -H "Content-Type: application/json" \
  -d '{ "from": "…", "to": "…", "subject": "…", "html": "…" }'