Error codes

Overview

The Inbox API returns consistent error responses with actionable information. This guide covers all error codes, their causes, and recovery strategies.

Error response format

All errors follow this structure:

{
  "error": {
    "code": "THREAD_NOT_FOUND",
    "message": "Thread with ID 'thread_invalid' not found",
    "status": 404
  }
}

Field	Description
`code`	Programmatic identifier for the error type
`message`	Human-readable description
`status`	HTTP status code

HTTP status codes

Status	Meaning	Common Causes
`400`	Bad Request	Invalid parameters, malformed JSON
`401`	Unauthorized	Missing or invalid API token
`403`	Forbidden	Token lacks required permissions
`404`	Not Found	Resource doesn’t exist
`409`	Conflict	Duplicate resource or state conflict
`422`	Unprocessable Entity	Valid JSON but invalid data
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server-side issue

Authentication errors

UNAUTHORIZED

Status: 401 When it occurs:

API token is missing from the request
API token is invalid or malformed
API token has expired or been revoked

Example response:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing authentication token",
    "status": 401
  }
}

How to fix:

Verify the Authorization header is present: Authorization: Bearer YOUR_TOKEN
Check for extra spaces or newlines in the token
Generate a new token from your Inbox dashboard

try {
  const { data } = await client.get('/team');
} catch (error) {
  if (axios.isAxiosError(error) && error.response?.status === 401) {
    console.error('Authentication failed. Check your API token.');
    // Prompt user to re-authenticate or check token
  }
}

# Verify your token format
curl https://inboxapp.com/api/v1/team \
  -H "Authorization: Bearer $INBOX_API_TOKEN" \
  -v  # Verbose output to see headers

FORBIDDEN

Status: 403 When it occurs:

Token is valid but lacks access to the resource
Resource belongs to a different team
Feature not available on your plan

Example response:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to access this resource",
    "status": 403
  }
}

How to fix:

Verify the resource belongs to your team
Check if your plan includes the requested feature
Contact support if you believe this is an error

Resource errors

THREAD_NOT_FOUND

Status: 404 When it occurs:

Thread ID doesn’t exist
Thread was deleted
Using platform ID instead of Inbox ID

Example response:

{
  "error": {
    "code": "THREAD_NOT_FOUND",
    "message": "Thread with ID 'thread_invalid' not found",
    "status": 404
  }
}

How to fix:

Verify you’re using the Inbox ID (CUID2 format like l44e15irdq4db30i77cgphhx), not the platform ID
Use /threads/lookup to find threads by prospect platform ID
Check if the thread was deleted

// Wrong: Using platform ID
await client.get(`/threads/1566123362161725440`);

// Correct: Using Inbox ID
await client.get(`/threads/l44e15irdq4db30i77cgphhx`);

// Correct: Lookup by platform ID
await client.get('/threads/lookup', {
  params: {
    externalPlatformId: '1876543210987654321',
    accountLinkId: 'df6jbw4h36qm5d9iu2sgn7kx'
  }
});

PROSPECT_NOT_FOUND

Status: 404 When it occurs:

Prospect ID doesn’t exist
Platform ID doesn’t match any known prospect
Prospect was never in a conversation with your team

Example response:

{
  "error": {
    "code": "PROSPECT_NOT_FOUND",
    "message": "Prospect not found",
    "status": 404
  }
}

How to fix:

Verify the platform ID is correct (X user IDs are numeric strings)
Prospects are created when they first message you or when you start a thread
Use /prospects/lookup to check if a prospect exists

// Check if prospect exists before operations
const { data: prospect } = await client.get('/prospects/lookup', {
  params: { platformId: '1876543210987654321' }
});

if (!prospect) {
  console.log('Prospect not in system. Start a conversation first.');
}

ACCOUNT_LINK_NOT_FOUND

Status: 404 When it occurs:

Account link ID doesn’t exist
Using platform ID instead of Inbox ID
Account was disconnected

How to fix:

List account links to get valid IDs: GET /account-links
Use the Inbox ID (CUID2 format), not the X user ID

// Get valid account link IDs
const { data: accountLinks } = await client.get('/account-links');
const validIds = accountLinks.map(a => a.id);
console.log('Valid account link IDs:', validIds);

TAG_NOT_FOUND

Status: 404 When it occurs:

Tag ID doesn’t exist
Tag was deleted

How to fix:

List tags to get valid IDs: GET /tags
Create the tag if it doesn’t exist

STATUS_NOT_FOUND

Status: 404 When it occurs:

Status ID doesn’t exist
Status was deleted

How to fix:

List statuses to get valid IDs: GET /statuses
Create the status if it doesn’t exist

MEMBER_NOT_FOUND

Status: 404 When it occurs:

Member ID doesn’t exist
Member was removed from the team

How to fix:

List members to get valid IDs: GET /members

Validation errors

VALIDATION_ERROR

Status: 400 When it occurs:

Required field is missing
Field value is wrong type
Value exceeds limits

Example response:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "status": 400,
    "details": {
      "field": "content",
      "issue": "Message content is required"
    }
  }
}

How to fix:

Check required fields for the endpoint
Verify data types match the API spec
Ensure string lengths are within limits

// Validate before sending
function validateMessage(content: string) {
  if (!content?.trim()) {
    throw new Error('Message content is required');
  }
  if (content.length > 10000) {
    throw new Error('Message exceeds 10,000 character limit');
  }
}

INVALID_CURSOR

Status: 400 When it occurs:

Cursor object is malformed
Cursor is from a different query
Cursor has expired

How to fix:

Use cursors exactly as returned from the API
Don’t modify cursor values
Start over from page 1 if cursor errors persist

State errors

DUPLICATE_THREAD

Status: 409 When it occurs:

Thread already exists for this prospect-account pair

How to fix: Use lookup before creating:

// Lookup first
const { data: existing } = await client.get('/threads/lookup', {
  params: { externalPlatformId, accountLinkId }
});

if (existing) {
  // Use existing thread
  return existing;
}

// Create only if none exists
const { data: created } = await client.post('/threads', {
  externalPlatformId,
  accountLinkId
});

DUPLICATE_TAG

Status: 409 When it occurs:

Tag with same name already exists

How to fix: Use a unique name or find the existing tag.

DUPLICATE_STATUS

Status: 409 When it occurs:

Status with same name already exists

How to fix: Use a unique name or find the existing status.

Rate limiting

RATE_LIMITED

Status: 429 When it occurs:

Too many requests in a short period

Example response:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Try again in 60 seconds.",
    "status": 429
  }
}

Response headers:

Retry-After: 60
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312800

How to fix:

Check the Retry-After header for wait time
Implement exponential backoff
Reduce request frequency

See the Rate Limits guide for detailed limits and backoff strategies.

Error handling pattern

A comprehensive error handler for all error types:

import axios, { AxiosError } from 'axios';

interface InboxError {
  code: string;
  message: string;
  status: number;
  details?: Record<string, unknown>;
}

async function handleInboxError(error: AxiosError<{ error: InboxError }>) {
  if (!axios.isAxiosError(error) || !error.response) {
    throw error;  // Not an API error
  }

  const { status, data, headers } = error.response;
  const errorInfo = data?.error;

  switch (status) {
    case 401:
      console.error('Authentication failed. Check your API token.');
      // Redirect to re-authenticate or refresh token
      break;

    case 403:
      console.error('Permission denied:', errorInfo?.message);
      break;

    case 404:
      console.error('Resource not found:', errorInfo?.code);
      // Handle based on error code
      if (errorInfo?.code === 'THREAD_NOT_FOUND') {
        // Maybe create the thread instead
      }
      break;

    case 409:
      console.error('Conflict:', errorInfo?.message);
      // Handle duplicates - usually fetch existing resource
      break;

    case 429:
      const retryAfter = parseInt(headers['retry-after'] || '60', 10);
      console.log(`Rate limited. Retry in ${retryAfter} seconds.`);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      // Retry the request
      break;

    case 500:
      console.error('Server error. Please try again later.');
      break;

    default:
      console.error('API error:', errorInfo?.message || error.message);
  }

  throw error;
}

// Usage
try {
  const { data } = await client.get(`/threads/${threadId}`);
} catch (error) {
  await handleInboxError(error as AxiosError);
}

Best practices

Always check error codes, not just messages

Error messages may change, but codes are stable:

// Good: Check code
if (error.response?.data?.error?.code === 'THREAD_NOT_FOUND') {
  // Handle missing thread
}

// Bad: Check message string
if (error.message.includes('not found')) {
  // Fragile
}

Validate before sending requests

Catch validation errors locally before making API calls to improve user experience.

Log errors with context

Include request details for debugging:

console.error('API Error:', {
  endpoint: '/threads',
  params: { threadId },
  error: error.response?.data
});

Handle 404s gracefully

Missing resources are often recoverable - create them or suggest alternatives.

Rate limits

Rate limiting details and backoff

Authentication

API token setup

Troubleshooting

Common issues and fixes

API reference

Complete endpoint documentation

Reference

Resources

Overview

Error response format

HTTP status codes

Authentication errors

UNAUTHORIZED

FORBIDDEN

Resource errors

THREAD_NOT_FOUND

PROSPECT_NOT_FOUND

ACCOUNT_LINK_NOT_FOUND

TAG_NOT_FOUND

STATUS_NOT_FOUND

MEMBER_NOT_FOUND

Validation errors

VALIDATION_ERROR

INVALID_CURSOR

State errors

DUPLICATE_THREAD

DUPLICATE_TAG

DUPLICATE_STATUS

Rate limiting

RATE_LIMITED

Error handling pattern

Best practices

Rate limits

Authentication

Troubleshooting

API reference

​Overview

​Error response format

​HTTP status codes

​Authentication errors

​UNAUTHORIZED

​FORBIDDEN

​Resource errors

​THREAD_NOT_FOUND

​PROSPECT_NOT_FOUND

​ACCOUNT_LINK_NOT_FOUND

​TAG_NOT_FOUND

​STATUS_NOT_FOUND

​MEMBER_NOT_FOUND

​Validation errors

​VALIDATION_ERROR

​INVALID_CURSOR

​State errors

​DUPLICATE_THREAD

​DUPLICATE_TAG

​DUPLICATE_STATUS

​Rate limiting

​RATE_LIMITED

​Error handling pattern

​Best practices

​Related

Rate limits

Authentication

Troubleshooting

API reference

Overview

Error response format

HTTP status codes

Authentication errors

UNAUTHORIZED

FORBIDDEN

Resource errors

THREAD_NOT_FOUND

PROSPECT_NOT_FOUND

ACCOUNT_LINK_NOT_FOUND

TAG_NOT_FOUND

STATUS_NOT_FOUND

MEMBER_NOT_FOUND

Validation errors

VALIDATION_ERROR

INVALID_CURSOR

State errors

DUPLICATE_THREAD

DUPLICATE_TAG

DUPLICATE_STATUS

Rate limiting

RATE_LIMITED

Error handling pattern

Best practices

Related