Error Codes

Note

The RelayPost dashboard uses a separate internal GraphQL API. This documentation covers the public REST API for external integrations.

When a REST API request fails, the response body contains a JSON error object with a machine-readable code and a human-readable message.

Error response format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "to", "message": "At least one recipient is required" }
    ]
  }
}

The details array is only present for VALIDATION_ERROR responses and contains field-level error information.

Error code reference

HTTP Status	Error Code	Description
400	VALIDATION_ERROR	Request body or query params failed validation
400	DOMAIN_NOT_VERIFIED	From address uses an unverified domain
400	RECIPIENTS_SUPPRESSED	One or more recipients are on the suppression list
401	AUTH_MISSING	No Authorization header provided
401	AUTH_INVALID	API key is invalid or revoked
403	TENANT_SUSPENDED	Organization account is suspended
404	NOT_FOUND	Resource does not exist or is not accessible
405	METHOD_NOT_ALLOWED	HTTP method not supported for this endpoint
429	RATE_LIMITED	API key rate limit exceeded
429	LIMIT_EXCEEDED	Organization email sending limit exceeded
500	INTERNAL_ERROR	Unexpected server error

Error examples

Authentication error

{
  "error": {
    "code": "AUTH_MISSING",
    "message": "No Authorization header provided"
  }
}

Validation error with field details

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "from", "message": "From email is required" },
      { "field": "subject", "message": "Subject is required" }
    ]
  }
}

Rate limit error

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API key rate limit exceeded"
  }
}

When rate limited, the response includes a Retry-After header with the number of seconds to wait.

Not found error

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

Handling errors

Best practices for handling REST API errors:

• Check the HTTP status code first to determine the error category
• Use the code field for programmatic error handling (e.g. switch on VALIDATION_ERROR vs AUTH_INVALID)
• Use the message field for user-facing error display
• For VALIDATION_ERROR responses, iterate over the details array to show field-specific messages
• Implement retry logic with exponential backoff for 429 and 500 responses
• Use the Retry-After header when present to determine wait time
• Log errors for debugging but don’t expose internal details to end users