API rate limits and best practices

Every Ody API key gets 600 requests per minute across /v1/api/* and the MCP endpoint — read the RateLimit-* headers on every response, and back off with the Retry-After value when you get a 429.

How the limit works

• The limit is per key, counted in a fixed 60-second window. Requests without a valid key are limited per IP instead.
• Every response — success or error — carries three standard headers:
  • RateLimit-Limit — your per-minute budget (600).
  • RateLimit-Remaining — requests left in the current window.
  • RateLimit-Reset — seconds until the window resets.
• Going over returns 429 with error code resource_exhausted and a Retry-After header (seconds). Wait at least that long before retrying.

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 23
Retry-After: 23

Staying under the limit

• Watch RateLimit-Remaining and slow down proactively as it approaches zero, rather than reacting to 429s.
• Use webhooks instead of polling. Subscribe an endpoint to events like message.received and Ody pushes activity to you — see Receive webhooks and verify signatures. If you must poll, every 10–30 seconds is plenty for a shared inbox.
• Retry with exponential backoff and jitter on 429 and 5xx, capping the retries. Honor Retry-After when present. For sends, pair retries with an Idempotency-Key so nothing double-sends — see Pagination, idempotency, and error handling.
• Request bigger pages (?limit= up to each endpoint's maximum) instead of many small ones when syncing data.

Key security best practices

• Scope every key to the minimum it needs. Deselect scopes at creation — a dashboard that only reads conversations should hold only conversations:read. See Get your Ody API key.
• Use test keys everywhere real texts would be a bug. Development environments and CI should run on ody_test_… keys so message sends are simulated — see Build safely with test mode.
• One key per integration. Separate keys for Zapier, your server, and an AI assistant mean you can revoke one without breaking the others, and the "last used" column in Settings → Developer API stays meaningful.
• Keep keys server-side. Never embed a key in mobile apps, browser JavaScript, or shared documents — anyone with the key can act as its creator within its scopes.
• Rotate and prune. Revoke keys you no longer use. Since the plaintext is only shown once, rotation means creating a new key, deploying it, then revoking the old one.

Related articles

• API overview and authentication
• Pagination, idempotency, and error handling
• Receive webhooks and verify signatures
• Build safely with test mode