Rate limits and errors

Use the error response's code to decide what to do. HTTP status alone is not enough: 429 RATE_LIMITED is a short request-rate limit, while quota errors require available monthly allowance.

Problem DetailsCopy Anchor Link

API errors use Content-Type: application/problem+json. For example:

{
  "type": "https://docs.watification.com/errors/rate-limited",
  "title": "Developer request failed",
  "status": 429,
  "code": "RATE_LIMITED",
  "detail": "The developer request could not be completed.",
  "instance": "/api/v1/otp/messages",
  "correlationId": "99999999-9999-4999-8999-999999999999"
}

Do not depend on the wording of title or detail. Open the error reference for causes, fixes, and retry guidance.

Request rate limitCopy Anchor Link

Each API key is limited to 20 requests per second in a fixed one-second window. OTP and COD requests, including GET status reads and idempotent repeats, share this limit.

Exceeding it returns 429 RATE_LIMITED with Retry-After: 1 (seconds). Wait at least that long, add jitter, and retry. Prefer webhooks to frequent status polling.

Monthly quotasCopy Anchor Link

Quotas use calendar-month periods and are workspace-wide. Amounts depend on your plan; unlimited allowances are supported. View your current limits under Developers > Overview and Sales > COD confirmation > Overview.

Idempotent repeats do not consume additional quota. Later send failures are not refunded. COD reminders, follow-up questions, and closing messages do not consume more COD quota units. Do not treat a quota error as a request-rate error or retry it every second.

IdempotencyCopy Anchor Link

All three public POST operations accept an optional Idempotency-Key string of at most 128 characters. Persist a unique, non-empty key per logical operation and reuse it with the same request after an uncertain result. Without a key, a repeated request can create another message or confirmation.

• OTP compares normalized recipient, sender, template name/language, and reference. The code is excluded: changing it with the same key does not replace the original code.
• COD compares all request values, including parameters. Named object key order does not affect the comparison. Confirmation create and refusal check have separate key namespaces in the workspace.
• A completed repeat returns the original 202 acceptance body, even after status advances. GET returns the current state.
• A changed fingerprint returns 409 IDEMPOTENCY_KEY_REUSED. Correct the request or use a new key only when you intend a new operation.

Retry guidanceCopy Anchor Link

Choose a maximum retry count and delay cap for your integration. For transient failures, one possible client policy is a random delay between zero and min(cap, base * 2^attempt); honor Retry-After as a minimum when present. These values are your client's policy, not an API SLA. An accepted request can fail later; do not blindly resubmit a webhook-reported failure without deciding whether a new send is appropriate.

Error code catalogCopy Anchor Link

The first table covers the public API-key routes. The second covers dashboard setup and management errors you may encounter while preparing an integration.

Public REST APICopy Anchor Link

Dashboard setup and managementCopy Anchor Link