Errors

Customer API Errors

Funnel Customer APIs use standard HTTP status codes to indicate whether a request succeeded or failed. Some errors include a structured JSON response body with additional details you can use for debugging and user-friendly handling.

ℹ️

How to interpret responses

HTTP status codes are grouped into ranges that describe the category of the response:

2xx: The request succeeded.
4xx: The request failed due to client-side input or permissions.
5xx: The request failed due to a server-side error.

ℹ️

Implementation note

Funnel's Customer API does not use a single error envelope. Not every error includes a JSON body, and the shape of the body depends on the endpoint. Always branch on the HTTP status code first, then inspect the body defensively — see the shapes below.

Error response format

Funnel's Customer API does not use a single error envelope. Depending on the endpoint, you will receive one of the shapes below. Always branch on the HTTP status code first, then inspect the body defensively — not every error includes a JSON body, and no shape is guaranteed across all endpoints.

Shape	When you'll see it
`{ "errors": { <field>: [<message>, …] } }`	Form or schema validation failures on most endpoints.
`{ "error_type": "<Type>", "errors": {…} }`	Structured validation or business-rule errors.
`{ "error_type": "<Type>", "message": "<text>" }`	Not-found or state errors without field-level detail.
`Plain-text or empty body`	Some endpoints return a non-JSON (or zero-length) body on certain error responses, for example a 404 on a single-resource lookup.

Examples:

errors object, no error_type

{
  "errors": {
    "client": {
      "people": ["Missing data for required field."]
    }
  }
}

ℹ️

Recommended handling

Check the HTTP status code first. Then look for error_type (useful for programmatic handling, when present), errors (field-level validation detail, when present), and message (human-readable, when present). These fields are not guaranteed to appear together, and some responses have no JSON body at all.

HTTP status codes

The Funnel Customer APIs may return the following HTTP status codes:

Code	Status	What it means
`200`	OK	The request succeeded.
`201`	Created	The request succeeded and created a new resource (for example, a prospect).
`400`	Bad Request	The request is invalid, often due to missing or malformed parameters.
`401`	Unauthorized	Authentication failed (missing or invalid API key).
`403`	Forbidden	The API key is valid, but it isn't permitted to access this resource or configuration.
`404`	Not Found	The requested resource doesn't exist, or the endpoint path is incorrect.
`405`	Method Not Allowed	The HTTP method isn't supported on this endpoint (for example, GET on an endpoint that only accepts DELETE). The body is an empty JSON string.
`422`	Unprocessable Entity	The request body wasn't valid JSON, or was missing the top-level object Funnel expects (for example, a `client` key). Unlike other error responses, the body here is plain text — either `Invalid Json` or `No Data Sent` — not JSON.
`429`	Too Many Requests	Request volume is too high. Reduce frequency and retry with backoff. Honor Retry-After if provided.
`5xx`	Server Errors	An internal error occurred on Funnel's side. Retry with backoff for transient failures.

⚠️

Rate limiting (429)

If you receive 429, reduce request frequency and retry using exponential backoff. Honor the Retry-After header if it is provided. Repeated 429s usually indicate the integration should switch to a bulk/sync approach instead of frequent polling.

Retry strategy and resilience

Production integrations should treat failures differently depending on the error class. The guidance below helps prevent retry storms and improves end-user experience.

Do not automatically retry most 4xx errors: Fix the request (parameters, permissions, endpoint path) before retrying.
Retry 429 with backoff: Slow down and respect any server guidance (such as Retry-After).
Retry transient 5xx errors: Use exponential backoff with jitter and a maximum retry cap.
Set timeouts: Always use reasonable connect and read timeouts to prevent hung workers.
Log with context: Include endpoint, method, status code, and any returned error_type or message to speed up debugging.

ℹ️

Avoid retry storms

If many requests fail at once (for example, during a deployment or outage), apply a circuit breaker or global backoff so you do not overwhelm your own systems or the API with synchronized retries.

Getting help

If you contact support about an error, include enough detail for us to reproduce or investigate quickly.

Customer account name (or the organization the key is issued to)
Endpoint URL and HTTP method
Timestamp and timezone
HTTP status code and any error response body (remove secrets)
Whether the issue is intermittent or consistently reproducible

ℹ️

Support contact

Email support@funnelleasing.com for API integration support.