Error Codes Reference

This document provides a comprehensive reference for all error codes returned by the Relay API.

Error Response Format

REST API Errors (/api/v1)

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Ticket not found",
    "details": {}
  }
}

tRPC Errors (/api/trpc)

All API errors follow a consistent format:

{
  "error": {
    "message": "Human-readable error description",
    "code": "ERROR_CODE",
    "data": {
      "code": "ERROR_CODE",
      "httpStatus": 400,
      "path": "procedure.name",
      "stack": "..." // Only in development
    }
  }
}

Error Fields

HTTP Status Codes

Common Error Codes

Authentication Errors

Validation Errors

Resource Errors

Rate Limiting

Server Errors

API-Specific Error Codes

Tickets API

Conversations API

Customers API

AI API

Articles API

Automations API

Integrations API

Macros API

SLA API

Scheduling API

Collections API

Webhooks

Error Handling Best Practices

1. Check Error Code First

try {
  const result = await trpc.tickets.get.query({ id: ticketId })
} catch (error) {
  if (error.data?.code === 'NOT_FOUND') {
    // Handle not found case
    showNotification('Ticket not found')
  } else if (error.data?.code === 'FORBIDDEN') {
    // Handle permission error
    redirectToLogin()
  } else {
    // Handle unexpected error
    showErrorMessage(error.message)
  }
}

2. Handle Rate Limits with Backoff

async function fetchWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn()
    } catch (error) {
      if (error.data?.code === 'TOO_MANY_REQUESTS') {
        const delay = Math.pow(2, i) * 1000 // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay))
      } else {
        throw error
      }
    }
  }
  throw new Error('Max retries exceeded')
}

3. Validate Input Before Sending

// Validate locally before API call
if (!isValidUUID(ticketId)) {
  throw new Error('Invalid ticket ID format')
}

if (!email.includes('@')) {
  throw new Error('Invalid email format')
}

4. Log Errors for Debugging

catch (error) {
  console.error('API Error:', {
    code: error.data?.code,
    message: error.message,
    path: error.data?.path,
    httpStatus: error.data?.httpStatus
  })
}

Rate Limits Summary

Rate Limit Headers

When approaching rate limits, the API returns headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705312800

Troubleshooting Common Errors

"UNAUTHORIZED" on Every Request

1. Check that your session cookie is included
2. Verify the cookie hasn't expired
3. Ensure you're using HTTPS
4. Check that the cookie domain matches

"NOT_FOUND" for Existing Resources

1. Verify the resource ID is correct
2. Check you're querying the right organization
3. Ensure the resource hasn't been soft-deleted
4. Verify your user has access to the resource

"BAD_REQUEST" Validation Errors

1. Check all required fields are present
2. Verify field types match the schema
3. Ensure strings meet length requirements
4. Check enum values are valid

"INTERNAL_SERVER_ERROR" Responses

1. Retry the request once
2. Check the API status page
3. If persistent, contact support with the error details
4. Include the timestamp and request path