Error codes

Every error returns a stable code, a human message and a link to the fix. Follow the steps below — it takes just a few minutes.

Before you begin#

• A Relay account and a test-mode API key
• curl or one of the official SDKs

Steps#

Common codes#

Code	HTTP	What to do
invalid_recipient	422	Check the number is in E.164 format, like +15550100001.
insufficient_scope	403	Give the key the scope named in the message.
rate_limited	429	Wait for Retry-After seconds.
provider_unavailable	503	Retry with backoff; Relay already tried a second carrier.

Still stuck?#

Include the request ID from the Relay-Request-Id response header — it lets us find your call in seconds.