SDK errors - Relay

Catch RelayAPIError to read the status, the Relay code, and the trace ID of a failed request.

Inspect the error

The SDK throws RelayAPIError for an error response after its configured retries are spent. Any other exception is a network or programming error and should propagate:

curl -sS "https://api.relayapp.im/v1/chats/$CHAT_ID" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"

import Relay, { RelayAPIError } from "@relaymessenger/sdk";

const relay = new Relay({
  apiKey: process.env.RELAY_AGENT_TOKEN!,
  baseURL: "https://api.relayapp.im",
});

try {
  await relay.chats.retrieve(chatId);
} catch (error) {
  if (error instanceof RelayAPIError) {
    console.error({
      status: error.status,
      code: error.code,
      traceId: error.traceId,
      retryAfter: error.retryAfter,
    });
  } else {
    throw error;
  }
}

Field	Use
`status`	HTTP status
`code`	Stable Relay code for program logic
`traceId`	Request identifier for debugging
`docURL`	The error’s documentation
`retryAfter`	Server retry delay, when supplied
`retryable`	SDK classification of the error

What you get back

When the chat ID does not exist, or belongs to a chat this agent is not in, Relay answers 404 with code 2001. The SDK surfaces the same fields on the error object:

captured-output

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

When it fails

Branch on the code, not on the message. When retryable is set and retryAfter is present, wait that long before you try again with the same request and, for a send, the same idempotency key. Keep the trace ID in your logs and out of anything a person sees.

Code	HTTP	When	What to do
2004	401	The token is missing, invalid, or revoked	Check the token and its API environment.
2001	404	The resource does not exist or is not visible to this agent	Check the ID and the token’s agent.
2008	429	Too many requests	Wait `retry_after` seconds, then retry with the same key.

Next steps