Error Codes Reference

The realay.io API uses standard HTTP status codes to indicate the success or failure of a request. In addition, the JSON response body contains a specific errorCode and a descriptive message.

HTTP Status Code Summary

• 2xx - Success
• 4xx - Client Error (e.g., bad request, authentication failure)
• 5xx - Server Error (an issue on realay.io's end)

Common Error Codes

Below is a list of common error codes that your application should be prepared to handle.

HTTP Status	errorCode	Description
400	BAD_REQUEST	The request was malformed or could not be parsed.
400	VALIDATION_ERROR	One or more fields failed validation (e.g., invalid phone number format).
400	MISSING_FIELD	A required field was missing from the request body.
401	UNAUTHORIZED	The API key is missing, invalid, or expired.
403	FORBIDDEN	You do not have permission to perform this action.
403	INSUFFICIENT_BALANCE	Your account balance is too low to send the message.
404	NOT_FOUND	The requested resource could not be found.
409	CONFLICT	The request could not be completed due to a conflict (e.g., alias already exists).
429	RATE_LIMIT_EXCEEDED	You have exceeded the API rate limit. Check the X-RateLimit-* headers.
500	INTERNAL_SERVER_ERROR	An unexpected error occurred on our servers. Please try again or contact support.

Example Error Response (400 Bad Request)

{
  "errorCode": "VALIDATION_ERROR",
  "message": "Invalid E.164 format for 'recipient' field."
}