Error codes and retries

The shape

Every non-2xx answer carries one body:

{
  "error": {
    "code": "concurrent_idempotent_requests",
    "message": "A request with this idempotency key is still being processed. Retry shortly.",
    "retryable": true,
    "request_id": "req_019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b"
  }
}

A failed item of a batch carries { "code", "message", "retryable" } in its own result.

Retrying

• When retryable is true, repeat the request with the same Idempotency-Key: the key makes sure a retry never sends a second email. A retry-after header says how many seconds to wait first; it comes with 429 rate_limit_exceeded and 409 concurrent_idempotent_requests.
• 500 errors and 502 upstream_unavailable are retryable. 502 outcome_unknown is not: the provider's answer was lost, so the email may have gone out, and it is failed rather than sent again (Never sent twice).
• 429 daily_quota_exceeded lasts until the next UTC day, or until the cap is raised in the project's settings.
• Validation errors (400, 422) need a changed request; issues names the fields.
• A body that is not valid JSON is 422 validation_error, and a body sent without a JSON content type is 415 unsupported_media_type. Send Content-Type: application/json, which fetch leaves out for a string body. A request with no body at all reads as {}.
• 501 not_implemented means the route is not served yet. It is not retryable.

Codes

Request ids and logs

Every response carries an x-request-id header. Send your own (8 to 128 characters from A-Z, a-z, 0-9, _ and -) and it comes back unchanged; otherwise the API makes one, such as req_019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b.

Every request made with a key is logged with its method, route pattern (/v1/emails/:id, never the concrete path), status, latency, key id, environment, mode, error code, request id, the caller's address and user agent, and the SHA-256 of its Idempotency-Key. Bodies and recipients are never logged. GET /v1/logs lists a key's own environment and mode, newest first, filtered by status, path, api_key_id, error_code, from_date and to_date; GET /v1/logs/{id} returns one. Logs are kept 30 days, and the console shows them under Logs.

curl "https://api.minket.com/v1/logs?error_code=rate_limit_exceeded" \
  -H "Authorization: Bearer $MINKET_API_KEY"

Updated 29 October 2026