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

Not every error includes a JSON body. When present, the body may include code, message, and optionally param.

Error response format

When an error response includes a JSON body, it uses the attributes below:

Attribute	Type	Description
`code`	`integer`	A machine-readable error code returned by the API.
`message`	`nullable string`	A human-readable description of what went wrong.
`param`	`nullable string`	The parameter associated with the error, when applicable.

Example:

Error response example

	{
	"code": 1234,
	"message": "Invalid parameter: start_date",
	"param": "start_date"
	}

ℹ️

Recommended handling

Use code for programmatic handling, message for logs (and optionally user-facing UI), and param to highlight invalid inputs in validation errors.

HTTP status codes

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

Code	Status	What it means
`200`	OK	The request succeeded.
`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.
`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 code 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.