tinysend
sign in

Error reference — tinysend agents

All API errors share one envelope:

{ "error": { "code": "...", "message": "..." } }

Some errors carry extra fields (upgrade_url, payment, cap) alongside code and message.

Status codes

  • 401 unauthorized — missing or invalid token. Don’t retry with the same token. Register or re-authenticate; the response’s WWW-Authenticate header points at the discovery metadata. See agent authentication.
  • 402 limit_exceeded — monthly email limit reached. Includes upgrade_url, enable_overage_url, and a payment object (protocol: "MPP"). Don’t retry as-is; upgrade, pay inline, or wait for the next period. See agent payments.
  • 402 spending_cap_reached — overage is on but the monthly spending cap is exhausted. Includes cap and increase_cap_url.
  • 403 forbidden — token is valid but lacks access to this resource or scope. Don’t retry; you need a different token, a claimed identity, or the resource isn’t yours.
  • 404 not_found — resource doesn’t exist or isn’t visible to you. Check the id; don’t blind-retry.
  • 409 already_subscribed — billing only: a subscription already exists.
  • 422 validation_error — request body or params failed validation. The message says what’s wrong. Fix the request; retrying unchanged will fail forever.
  • 429 rate_limited — too many requests. Retry after the window resets (see headers below).

Rate limits

60 requests per minute per token. Every response carries:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 12
X-RateLimit-Reset: 1718200000

X-RateLimit-Reset is a unix timestamp (seconds). On 429, sleep until that time and retry. Watch X-RateLimit-Remaining and pace yourself instead of hammering until you hit the wall.

Retry guidance

  • retryable: 429 (after reset), 5xx and network errors (exponential backoff)
  • retryable after action: 401 (new token), 402 (upgrade or payment)
  • not retryable: 403, 404, 422 — fix the request first

Questions?

Contact us at hi@tinysend.com.