Errors

Every error response from https://api.primitive.dev/v1 uses the same envelope so agents and SDKs can branch on machine-readable codes without parsing HTTP status text or scraping prose.

Envelope

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key",
    "request_id": "req_01HZ8K3M2N7Q5R8S9T0V1W2X3Y"
  }
}

• error.code is a stable machine-readable identifier. Agents and SDKs branch on this value, not on the human-readable message.
• error.message is a short human-readable description. It can change between releases without warning. Do not parse it.
• error.request_id echoes the server-issued request id and is also returned in the X-Request-Id response header. Include this in support escalations so we can find the failing request in our logs.

Validation errors additionally carry an error.details object listing the rejected fields:

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Request body failed validation",
    "details": { "from": "must be a verified outbound domain" },
    "request_id": "req_..."
  }
}

Send denials (recipient_not_allowed) additionally carry an error.gates[] array. Each entry describes one failed permission gate so an agent can branch on a stable reason and self-correct:

{
  "success": false,
  "error": {
    "code": "recipient_not_allowed",
    "message": "Recipient is not allowed for this organization yet",
    "gates": [
      {
        "name": "send_to_known_addresses",
        "reason": "recipient_not_known",
        "message": "You have not exchanged authenticated mail with this address yet.",
        "subject": "alice@external.com",
        "fix": { "action": "wait_for_inbound", "subject": "alice@external.com" },
        "docs_url": "https://docs.primitive.dev/docs/sending"
      }
    ],
    "request_id": "req_..."
  }
}

• Branch on gates[].reason (and act on gates[].subject), never the human message. Reasons are stable and additive — new gates may appear, existing ones are not renamed in place.
• gates[].fix is present only when there is a customer-side action; some denials (for example, the sender must fix their own DNS) carry no fix. When present, fix.subject is the entity the action applies to.

Error codes

Send and reply errors

These codes come from POST /v1/send-mail, the reply/forward endpoints, and the read endpoints.

Outbound relay failures

When the outbound relay itself fails, the send returns one of these. The same Idempotency-Key makes a retry safe.

x402 payment errors

These codes come from the x402 endpoints (synthetic and email-native). See Collecting Payments and x402 over Email. x402 is in an invite-only soft launch; an org without access gets feature_disabled.

The email-native settle path additionally enforces per-payee-org settle caps. These surface as a reject step on the thread and a payment.failed webhook event (not as an API error code, because the settle happens after the payment reply arrives):

The daily and monthly caps are raisable by the Primitive team; the per-settle ceiling is fixed. See the Settle limits section in x402 over Email.

Structured failure reasons

The four top-level codes above are stable umbrellas. To let an auto-pay agent branch on why a payment failed without parsing the human message, every x402 failure also carries machine-readable detail:

{
  "success": false,
  "error": {
    "code": "settlement_failed",
    "message": "facilitator settlement failed",
    "details": {
      "reasons": ["facilitator_unavailable"],
      "failure_category": "settlement"
    }
  }
}

• details.reasons is an array of stable subreason codes (a single-element array when there is one reason). The human message is preserved unchanged alongside it.
• details.failure_category is one of declined, cap, verification, settlement.
• The same failure_category and reasons are also added to the payment.failed webhook payload, so an async subscriber can branch identically.

The subreason codes per failure path:

payment_declined (category declined) — the payer's spend policy refused it. All permanent until the policy changes; the challenge stays pending so you can adjust and retry.

payment_verification_failed (category verification) — the signed payment did not match the recorded challenge. All permanent; re-sign against the exact challenge. reasons may carry several codes at once (index-aligned with the message).

settlement_failed (category settlement) — the on-chain settlement did not complete. This is where retryable vs permanent vs misconfig diverge:

challenge_expired (category settlement) — reasons: ["challenge_expired"]. Permanent for this challenge; the payee must issue a new one.

Settle-cap rejects (category cap) — the email-native rail's per-payee-org cap rejects (settle_daily_cap_exceeded, settle_monthly_cap_exceeded, amount_exceeds_per_settle_ceiling, documented above) surface with failure_category: "cap" in the payment.failed webhook payload.

Only facilitator_unavailable (and the generic settlement_failed) are retryable, and only those set Retry-After. Every other reason is permanent or a misconfiguration: retrying the same payment will fail the same way.

Rate-limit responses

429 responses carry a Retry-After header plus the standard rate-limit headers:

Retry-After: 30
ratelimit-limit: 120
ratelimit-remaining: 0
ratelimit-reset: 1718900000

Retry-After is in seconds; ratelimit-reset is a Unix timestamp (seconds) when the window resets; ratelimit-limit reflects your plan's per-minute API limit. Agents should sleep for at least Retry-After seconds before retrying the same operation. The body matches the standard envelope — branch on the 429 status, since the code is either rate_limited (org-wide limiter, /v1/send-mail) or rate_limit_exceeded (per-resource limiters):

{ "success": false, "error": { "code": "rate_limited", "message": "Rate limit exceeded" } }

Idempotency

The /send-mail endpoint accepts an optional Idempotency-Key request header. When provided, replays of the same key return the original outcome (including the Idempotency-Key response header echoing the effective value) rather than firing a second send. Use this for any operation an agent might retry after a network failure.

If you omit the header, Primitive derives a key from the canonical request payload and returns it in the Idempotency-Key response header so you can use it on a follow-up retry.

Webhook signature failures

Webhook delivery failures appear in webhook event logs, not in API responses. See the signature verification guide for verifier logic.

Versioning and deprecation

The error envelope is part of the v1 contract. Breaking changes will only land in a new major version (/v2). See API versioning.