Reference

Error Codes

All API errors follow a consistent JSON format with human-readable messages and machine-readable codes for reliable error handling.

Error Response Format

Every error response returns a JSON body containing two fields: a human-readable error message and a machine-readable code string.

Use the code field for programmatic error handling — the error message may change across versions.

Error Shape

JSON Error Response

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "The 'phone' field must include a country code.",
  "code": "validation_error"
}

Error Code Reference

Code	HTTP Status	Meaning
`unauthorized`	401	Missing or invalid API key.
`forbidden`	403	Valid key but insufficient scope or permission.
`not_found`	404	Resource does not exist or access denied.
`validation_error`	422	Request body failed validation.
`conflict`	409	Action conflicts with current state.
`rate_limited`	429	Rate limit exceeded.
`internal_error`	500	Server error — no internal details are leaked.

Common Error Scenarios

Missing API Key

unauthorized

{
  "error": "API key is required.",
  "code": "unauthorized"
}

Insufficient Scope

forbidden

{
  "error": "Insufficient scope: requires leads:write",
  "code": "forbidden"
}

Invalid Request Body

validation_error

{
  "error": "The 'name' field is required.",
  "code": "validation_error"
}

Rate Limit Hit

rate_limited

{
  "error": "Rate limit exceeded. Retry after 8 seconds.",
  "code": "rate_limited"
}

Error Handling Best Practices

Always check the HTTP status code first, then parse the JSON body for the machine-readable code.

Use the code field for programmatic branching — the error message is for humans and may change.

Implement retry logic with exponential backoff for rate_limited (429) errors.

Log the full error response for debugging, but never expose internal_error details to end users.

Handle not_found gracefully — it may indicate the resource was deleted or access was revoked.

For validation_error responses, display the error message to guide the user in correcting their input.

Error Handler Example

Error Handling (JavaScript)

async function syncFloRequest(url, options) {
  const res = await fetch(url, options);

  if (!res.ok) {
    const body = await res.json();

    switch (body.code) {
      case 'rate_limited':
        const retryAfter = res.headers.get('Retry-After');
        await sleep(retryAfter * 1000);
        return syncFloRequest(url, options); // retry
      case 'unauthorized':
        throw new Error('Invalid API key');
      case 'validation_error':
        throw new Error(body.error); // show to user
      default:
        throw new Error(`API error: ${body.code}`);
    }
  }

  return res.json();
}

Essentials

Technical API