Error Codes - Relay Messenger

Every Relay API error uses the same JSON envelope.

{
  "error": {
    "status":404,
    "code":2001,
    "message":"Resource not found.",
    "doc_url":"https://docs.relayapp.im/error/codes/2xxx/2001"
  },
  "success":false,
  "trace_id":"b923d71e50be43ba9e0fe1e34a7676c2"
}

Use error.code for program logic. Record trace_id when diagnosing a failed request.

Envelope fields

Field	Use
`error.status`	HTTP status
`error.code`	Stable numeric program key
`error.message`	Readable diagnostic explanation
`error.doc_url`	Direct link to the code page
`error.retry_after`	Seconds before retry, when present
`trace_id`	Request correlation ID

Error code ranges

Range	Category	Default retry rule
1xxx	Request errors	Fix the request before retrying
2xxx	Authentication, resource, state, or limit errors	Follow the code-specific guidance
3xxx	Relay server errors	Retry only when the command is idempotent

1xxx request errors

Code	Meaning
1004	Mentioned Handle is not in the Chat
1005	Request or current state is invalid

2xxx resource errors

Code	Meaning
2001	Resource not found
2003	Permission denied
2004	Authentication required
2005	Attachment owner unavailable
2006	Invalid or unsupported content
2007	Attachment is not ready
2008	Request was rate limited
2015	Mentioned Handle left the Chat
2023	Mentions require a group Chat
2025	Blocked Handle not found
2026	Handle is blocked

3xxx server errors

Code	Meaning
3006	Unexpected Relay server error