Docs · Errors

Errors and rate limits

A failed request answers with an HTTP status and a problem document (RFC 9457, application/problem+json). Branch on the status and the problem type; show detail to a developer, not to an end user.

The error format

{
  "type": "https://owlpost.to/problems/idempotency-conflict",
  "title": "This Idempotency-Key was used for a different request",
  "status": 409,
  "detail": "Use a new key for a new message; a retry must repeat the original request exactly.",
  "instance": "01J9ZQ5X7K3M2N4P6R8S0T1V2W"
}

One exception: a body that is not valid JSON, or is missing a required field, on the domain, webhook, inbound and suppression routes is refused by the web framework before Owlpost reads it, with a short plain-text 4xx instead of a problem document. The send routes always answer with a problem.

Status codes and problem types

Retry 429, 500, 502 and 503 with backoff. With an Idempotency-Key, retrying a send is always safe. Do not retry other 4xx answers unchanged.

Rate limits

Each API key may make 60 requests a minute. A batch counts as one request per message in it. Over the limit, the answer is 429 with the slug rate-limited, and nothing was stored. The 429 does not carry a Retry-After header yet, so back off on your side: wait a few seconds, then retry with growing pauses.

The limit applies to the email send and read routes, domains, webhooks and every inbound route. The suppression and topic routes are not rate-limited today.

When the rate limiter itself cannot be reached, the API refuses rather than letting traffic through unmetered, so a 429 can also mean "try again in a moment".

Agent inboxes have two more limits, counted per hour: 60 messages from one inbox and 10 into one thread (see loop limits).

Size limits