RATE_LIMIT_EXCEEDED - Blujay API

HTTP status	Retryable
`429`	Yes

What happened

You hit a limit. It can be the API request rate for your credential, a sending limit on the phone number, or the capability-check quota. error.details[0].limit_type says which (for capability checks, error.details[0].limit).

How to fix it

Wait for the number of seconds in the Retry-After header (also error.retry_after; RateLimit-Reset is the same number of seconds), then retry with the same idempotency key. For sends, check send_status and limits on GET /v1/phone-numbers before sending more.

This error is safe to retry. Wait for the Retry-After header when it is present. If the endpoint takes an Idempotency-Key, reuse the same key so a retry never creates a duplicate.

Example response

An illustrative example. The message wording and the contents of details vary; branch on error.code.

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "type": "rate_limit",
    "http_status": 429,
    "retryable": true,
    "doc_url": "https://docs.blujay.io/errors/rate-limit-exceeded",
    "details": [
      {
        "limit_type": "public_api_write",
        "scope": "api_key",
        "limit": 120,
        "remaining": 0,
        "reset_at": "2026-10-14T17:31:00.000Z"
      }
    ],
    "retry_after": 12
  },
  "trace_id": "trc_8f2a1c0e4b7d",
  "timestamp": "2026-10-14T17:30:48.000Z"
}

Still stuck?

Email support@blujay.io with the trace_id from the error response. See Errors for the response format.