Error Reference

Complete reference of all error responses returned by the Gravity SMS API. Every error follows the same JSON format. Use this page to look up specific error messages and understand how to resolve them.

Error format

All error responses return a JSON object with a single error key:

Error response

{
  "error": "Description of what went wrong"
}

400 Bad Request

The request is malformed, missing required fields, or contains invalid values. Fix the request before retrying.

Error message	Endpoint	Fix
`to, from, and body are required`	`POST /v1/sms/send`	Include all three fields in the request body.
`to and from must be valid E.164 phone numbers`	`POST /v1/sms/send`	Use E.164 format: `+` followed by 9–15 digits (e.g., `+15551234567`).
`body must be 1-1600 characters`	`POST /v1/sms/send`	Message body must not be empty and must not exceed 1,600 characters.
`Invalid messageId format`	`GET /v1/sms/status/:messageId`	Use the format `msg_` + 12 hex characters.
`name must be 1-100 characters`	`POST /v1/apps/register`	Provide a non-empty name of 100 characters or fewer.
`Invalid tenantId format`	`POST /v1/apps/register`	Use the format `tenant_` + 16 hex characters.
`Tenant not found or not active`	`POST /v1/apps/register`	Verify the tenant ID exists and the tenant is in active status.
`Invalid webhookUrl: must be https:// in production, max 2000 chars`	`POST /v1/apps/register`, `PUT /v1/apps/:appId`	Provide a valid HTTPS URL of 2,000 characters or fewer.
`Invalid appId format`	`GET`, `PUT`, `DELETE /v1/apps/:appId`	Use the format `app_` + 16 hex characters.
`App has no webhookUrl configured`	`POST /v1/apps/:appId/test-webhook`	Set a `webhookUrl` on the app before testing.
`Missing token`	`GET /v1/rc/connect`	Use the full `connectUrl` returned by the connect-token endpoint.
`Invalid or expired token`	`GET /v1/rc/connect`	Generate a new connect token. Tokens are single-use and expire quickly.

401 Unauthorized

Authentication failed. The API key is missing, malformed, or does not match any active app.

Error message	Cause	Fix
`Missing or invalid API key`	No `Authorization` header, or the value does not start with `Bearer sgw_`.	Include the header: `Authorization: Bearer sgw_...`
`Invalid API key`	The key format is correct but it does not match any active app in the system.	Verify the key is correct. If lost, rotate the key to generate a new one.

403 Forbidden

The API key is valid but lacks permission for the requested action.

Error message	Cause	Fix
`Admin API key required to register new apps`	An app-role key attempted to register a new app.	Use an admin-role API key.
`Tenant suspended or inactive`	The tenant associated with this API key is not in active status.	Contact your platform administrator to restore the tenant.
`HTTPS required`	The request was made over HTTP in a production environment.	Use `https://` for all API requests.

404 Not Found

The requested resource does not exist or is not accessible with the current API key.

Error message	Endpoint	Fix
`Message not found`	`GET /v1/sms/status/:messageId`	Verify the message ID. App-role keys can only access messages within their own tenant.
`App not found`	`GET`, `PUT`, `DELETE /v1/apps/:appId`	Verify the app ID. App-role keys can only access apps within their own tenant.

413 Payload Too Large

The request body exceeds the maximum allowed size.

Error message	Cause	Fix
`Payload too large`	Request body exceeds 100 KB.	Reduce the size of the request body.

429 Too Many Requests

A rate limit has been exceeded. The response includes a Retry-After header with the number of seconds to wait.

Error message	Cause	Fix
`Too many requests`	Per-key API rate limit exceeded (100/min for app, 500/min for admin), failed auth IP block (10 attempts in 5 min), or connect token limit (5/tenant/hour).	Wait for the number of seconds in the `Retry-After` header before retrying.

See Rate Limits for a breakdown of all rate limit tiers and handling strategies.

500 Internal Server Error

An unexpected error occurred on the server. This is retryable with exponential backoff.

Error message	Cause	Fix
`Internal server error`	Unexpected server-side failure. In production, detailed error information is never exposed.	Retry with exponential backoff (start at 1 second). If the error persists, include the `X-Request-Id` header value when reporting the issue.

WebSocket errors

WebSocket errors are delivered as JSON messages with type: "auth_error". The connection is closed with code 1008 (Policy Violation) after sending the error.

Error message	Cause	Fix
`Invalid JSON`	The first message sent was not valid JSON.	Send a valid JSON auth message: `{"type":"auth","apiKey":"..."}`
`Invalid API key`	The API key does not match any active app.	Verify the API key is correct and the app is active.
`Send auth first`	A non-auth message was sent before authenticating.	Send the auth message immediately after the connection opens.

Message-level errors

These are not HTTP errors. They appear in the error field of a message object when the message has status: "failed". Check via GET /v1/sms/status/:messageId or the sms_status WebSocket event.

Error message	Cause	Fix
`RingCentral not connected for this tenant`	The tenant has no active RingCentral connection.	Connect a RingCentral account via the OAuth flow before sending messages.
`Phone number +15551234567 is not registered in this RingCentral account`	The "from" number is not SMS-enabled or not part of the connected RingCentral account.	Use an SMS-enabled number from your RingCentral account. Check status at `GET /v1/rc/status`.

Retryable vs. permanent errors

Status	Retryable	Strategy
`400`	No	Fix the request.
`401`	No	Check your API key.
`403`	No	Check role and tenant status.
`404`	No	Verify the resource ID.
`413`	No	Reduce payload size.
`429`	Yes	Wait for `Retry-After` seconds.
`500`	Yes	Retry with exponential backoff.

Related docs

Error Handling Guide — Strategies and code examples
Rate Limits — All rate limit tiers and handling
Authentication — API key format and roles