Errors, Limits, and Retry

Error response format

All error responses use the RFC 7807 ProblemDetails structure:

      
        {
          "type": "https://tools.ietf.org/html/rfc7807",
          "title": "Validation error",
          "status": 422,
          "detail": "The 'to' field must be a valid E.164 phone number.",
          "traceId": "00-abc123-def456-00"
        }

The traceId field correlates to distributed tracing. Include it in support requests.

Status code reference

Code	Title	Recommended action
`400`	Bad Request	Fix request syntax
`401`	Unauthorized	Refresh token or verify API key
`403`	Forbidden	Check API key rights or account policy
`404`	Not Found	Verify ID and account ownership
`409`	Conflict	Check existing state before retrying
`422`	Validation Error	Inspect `detail` for constraint violation
`429`	Too Many Requests	See rate limits below
`500`	Internal Server Error	Retry with backoff; file support ticket if persistent

Rate limits

When a rate limit is exceeded the response includes a Retry-After header (when present):

      
        {
          "type": "https://arelhub.com/errors/rate-limit",
          "title": "Too Many Requests",
          "status": 429,
          "detail": "Request rate limit exceeded. Retry after 30 seconds.",
          "retryAfter": 30
        }

Quota limits

Quota depletion returns a distinct 429. Check remaining quota before bulk sends:

      
        GET /v1/user/quota/subaccounts/{subaccountId}
        Authorization: Bearer eyJ...

Retry posture

Error	Retry?	Strategy
`400`, `422`	No	Fix request and resubmit
`401`	Conditional	Refresh token, then retry once
`403`	No	Contact support if unexpected
`404`	No	Verify resource ID
`429`	Yes	Respect `Retry-After`; exponential backoff
`500`	Yes	Exponential backoff with jitter; cap at 3-5 attempts
Network timeout	Yes	Treat timed-out requests as idempotent; check status first

Exponential backoff formula

      
        delay = min(base x 2^attempt, maxDelay) + random(0, jitter)
        // Recommended: base=1s, maxDelay=30s, jitter=500ms

Idempotent requests

Message submission is not idempotent by default. If a POST /v1/accounts/{accountId}/messages request times out, check status before retrying. Use the externalId field on submission to correlate your internal request ID with ArelHub's message ID.

Support

For persistent errors or incidents, include in your support request: traceId, request timestamp (UTC), endpoint and HTTP method, and anonymized request body.

Contact support

← Webhooks · API Reference →