Errors and rate limits

When to use this guide: Use this reference when an OutboundSync API request fails, returns 401, 403, or 429, or needs retry logic.

OutboundSync API v1 uses standard HTTP status codes. Error responses include a human-readable message; most also include statusCode and error.

Error response shape

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

Treat message and the HTTP status code as the stable troubleshooting fields. Some framework-generated responses can vary by status.

Status codes

Status	Meaning	Common cause	What to do
`200`	Success	The key is valid and has at least one API-enabled connection.	Continue using the response.
`401`	Unauthorized	Missing, malformed, revoked, rotated, or invalid API key.	Confirm the `Authorization: Bearer osapi_...` header and rotate the key if needed.
`403`	Forbidden	The key is valid, but API access is not enabled for any accessible CRM connection.	Ask an admin to enable API access for the connection.
`429`	Too many requests	The IP or account exceeded the current fixed-window limit.	Respect the `Retry-After` header before retrying.
`500`	Server error	Unexpected server-side failure.	Retry later; contact support if it repeats.

401 invalid API key

OutboundSync returns a uniform 401 for missing, malformed, invalid, revoked, and rotated keys.

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

The response includes this header so clients know Bearer authentication is expected:

WWW-Authenticate: Bearer realm="OutboundSync API"

403 API access disabled

A key can be valid but still unable to use the API. This happens when no accessible CRM connection has API access enabled.

{
  "statusCode": 403,
  "message": "API access is not enabled for this account",
  "error": "Forbidden"
}

Fix this in the OutboundSync admin app by enabling API access for the CRM connection, then retry GET /api/v1/me.

429 rate limit exceeded

GET /api/v1/me currently applies two fixed-window limits:

Layer	Limit	Window	When it applies
IP address	120 requests	60 seconds	Before API key validation
Account owner	120 requests	60 seconds	After API key validation

When a request is rate limited, OutboundSync returns 429 and a Retry-After header with the number of seconds until the current window resets.

Retry-After: 37

Retry pattern

async function getOutboundSyncMe(apiKey) {
  const response = await fetch('https://app.outboundsync.com/api/v1/me', {
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  if (response.status === 429) {
    const retryAfter = response.headers.get('Retry-After') ?? '60';
    throw new Error(`OutboundSync rate limit exceeded. Retry after ${retryAfter} seconds.`);
  }

  if (response.status === 401) {
    throw new Error('OutboundSync API key is missing, invalid, revoked, or rotated.');
  }

  if (response.status === 403) {
    throw new Error('OutboundSync API access is not enabled for this account.');
  }

  if (!response.ok) {
    throw new Error(`OutboundSync API request failed with ${response.status}.`);
  }

  return response.json();
}

Ask an AI coding assistant

Add retry handling for OutboundSync API calls.
For 429, read Retry-After and wait that many seconds before retrying once.
For 401, tell the user to check the Bearer osapi_ key.
For 403, tell the user to enable API access for the CRM connection in OutboundSync.