Public beta

Error Handling

The Zippex API uses conventional HTTP status codes and returns structured JSON error responses so you can handle failures programmatically.

Error response format

All errors follow a consistent structure:

Error response

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_required_param",
    "message": "The pickup_address parameter is required.",
    "param": "pickup_address"
  }
}

Field	Type	Description
type	string	The category of error. Use this for broad error handling.
code	string	A machine-readable error code. Use this for specific error handling.
message	string	A human-readable description of the error. Not intended for end users.
param	string \| null	The parameter that caused the error, if applicable.

Error types

Type	Meaning
invalid_request_error	The request was malformed or contained invalid parameters. Check the `param` field for which parameter to fix.
authentication_error	The API key is missing, invalid, or has been revoked.
rate_limit_error	Too many requests. Back off and retry after the time indicated in the `X-RateLimit-Reset` header.
not_found_error	The requested resource does not exist or does not belong to your account.
api_error	An unexpected error on the Zippex side. These are rare. Retry with exponential backoff.

HTTP status codes

Status	Meaning	Typical cause
200	OK	Request succeeded.
201	Created	Resource created successfully.
400	Bad Request	Missing or invalid parameters.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	API key does not have permission for the requested action.
404	Not Found	The requested resource does not exist.
410	Gone	The resource has expired (e.g., an expired quote).
429	Too Many Requests	Rate limit exceeded. See the Rate Limits page.
500	Internal Server Error	Something went wrong on the Zippex side. Retry with backoff.

Common error codes

Code	HTTP	Description	How to fix
missing_required_param	400	A required parameter is missing.	Check the `param` field and include the missing parameter.
invalid_param_value	400	A parameter has an invalid value.	Check the `param` field and ensure the value matches the expected format.
invalid_api_key	401	API key is invalid or revoked.	Double-check your key and ensure it has not been revoked in the dashboard.
quote_expired	410	The quote has expired (older than 15 minutes).	Request a new quote and use the new `quote_id`.
delivery_not_cancellable	400	The delivery cannot be cancelled in its current status.	Deliveries with status `picked_up` or later cannot be cancelled.
address_not_serviceable	400	The pickup or dropoff address is outside the Zippex service area.	Verify the address is within a supported city. Contact support for service area questions.
resource_not_found	404	The requested ID does not exist.	Verify the ID is correct. Test-mode resources are not accessible with live keys and vice versa.
rate_limit_exceeded	429	You have exceeded 100 requests per minute.	Wait until `X-RateLimit-Reset` and retry. Implement exponential backoff.

Handling errors in code

async function createDelivery(params) {
  const response = await fetch('https://api.zippex.com/v1/deliveries', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ZIPPEX_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(params),
  });

  if (!response.ok) {
    const { error } = await response.json();

    switch (error.type) {
      case 'invalid_request_error':
        "color:#6a9955">// Fix the request — check error.param and error.code
        console.error(`Bad request: ${error.message} (param: ${error.param})`);
        break;

      case 'authentication_error':
        "color:#6a9955">// Check your API key
        console.error('Authentication failed — verify your API key.');
        break;

      case 'rate_limit_error':
        "color:#6a9955">// Wait and retry
        const resetAt = response.headers.get('X-RateLimit-Reset');
        console.error(`Rate limited. Retry after ${resetAt}`);
        break;

      case 'api_error':
        "color:#6a9955">// Retry with backoff
        console.error('Zippex server error — retrying...');
        break;

      default:
        console.error(`Unexpected error: ${error.message}`);
    }

    throw new Error(error.message);
  }

  return response.json();
}