Common Errors

This guide covers common API errors and how to resolve them. If you encounter an error not listed here, please contact support.

AUTHENTICATION_REQUIRED

Authentication required

API key is missing or invalid

Solution

Check that you're including a valid API key in the Authorization header

// ❌ Missing API key
const client = new Settler({});

// ✅ Correct
const client = new Settler({
  apiKey: process.env.SETTLER_API_KEY,
});

RATE_LIMIT_EXCEEDED

Rate limit exceeded

You've exceeded your rate limit

Solution

Wait for the rate limit window to reset, or upgrade your plan

// Check rate limit headers
const response = await fetch('/api/v1/jobs', {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
  },
});

const remaining = response.headers.get('X-RateLimit-Remaining');
const reset = response.headers.get('X-RateLimit-Reset');

WORKSPACE_NOT_FOUND

Workspace not found

The workspace ID doesn't exist or you don't have access

Solution

Verify the workspace ID and ensure you have membership

// Check workspace membership
const membership = await getWorkspaceMembership(workspaceId);
if (!membership.authorized) {
  // Handle unauthorized access
}

VALIDATION_ERROR

Validation error

Request payload is invalid

Solution

Check the API reference for required fields and formats

// ❌ Missing required field
await client.jobs.create({
  name: "My Job",
  // Missing source and target
});

// ✅ Correct
await client.jobs.create({
  name: "My Job",
  source: { adapter: "stripe", config: {} },
  target: { adapter: "shopify", config: {} },
});