Error Handling

Safaribid uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

Codes in the 2xx range indicate success.
Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.).
Codes in the 5xx range indicate an error with Safaribid's servers.

Error Object

When an error occurs, Safaribid returns a JSON object with the following structure:

{
  "error": {
    "code": "invalid_parameters",
    "message": "The pickup address was not recognized.",
    "param": "pickup.address",
    "doc_url": "https://docs.safaribid.com/errors/invalid_parameters"
  }
}

HTTP Status Codes

Code	Description
`200 - OK`	Everything worked as expected.
`400 - Bad Request`	The request was unacceptable, often due to missing a required parameter.
`401 - Unauthorized`	No valid API key provided.
`402 - Request Failed`	The parameters were valid but the request failed (e.g., insufficient wallet balance).
`403 - Forbidden`	The API key does not have permissions to perform the request.
`404 - Not Found`	The requested resource doesn't exist.
`409 - Conflict`	The request conflicts with another request (e.g., duplicate idempotency key).
`429 - Too Many Requests`	Too many requests hit the API too quickly.
`500, 502, 503, 504 - Server Errors`	Something went wrong on Safaribid's end.

Error Codes

Code	Possible Recovery
`insufficient_balance`	Add funds to your Safaribid Business Wallet.
`rider_unavailable`	No riders are currently active in the requested area. Try again later.
`invalid_address`	Verify the lat/lng coordinates or the human-readable address.
`idempotency_key_reused`	Generate a new unique key for the new request.
`package_too_heavy`	Split the items into multiple delivery requests.

Handling Errors in Code

try {
  const delivery = await client.deliveries.create({ ... });
} catch (error) {
  if (error.code === 'insufficient_balance') {
    alert('Please top up your wallet to continue.');
  } else {
    console.error('An unexpected error occurred:', error.message);
  }
}

try:
    delivery = client.deliveries.create( ... )
except SafaribidError as e:
    if e.code == 'insufficient_balance':
        print("Please top up your wallet.")
    else:
        print(f"Error: {e.message}")

Error Handling

Error Handling

Error Object

HTTP Status Codes

Error Codes

Handling Errors in Code

On this page