Errors, rate limits and best practices

Every error answers with the same JSON shape. Check success on every response and branch on error.code.

Error format#

{  "success": false,  "message": "Validation failed",  "error": {    "code": "VALIDATION_ERROR",    "message": "Latitude must be between -90 and 90"  }}

Some calls of the Trips API also return an optional error.details object, for example details.batch_id.

HTTP status codes#

Error codes#

Rate limits#

There are no explicit rate limits at the moment. The recommendation is a maximum of 100 requests per minute per API user. Excessive requests may be throttled.

Best practices#

Tokens#

• Store tokens in environment variables or secure storage.

• Tokens expire after 90 days. Build refresh logic: on a 401, log in again.

• Never expose tokens in client-side code or logs.

Errors and retries#

• Always check the success field.

• Retry 5xx responses. A 422 ROUTE_NOT_FOUND and an unreadable body (400 BAD_REQUEST, 415, 413) cannot succeed on retry, so fix the request instead.

• Send an Idempotency-Key on POST /api/trips so a retry after a timeout is safe.

• Treat webhook deliveries as idempotent: the same update can arrive more than once.

Requests#

• Use the estimate call before creating orders if you show distance to customers.

• Cache estimates when appropriate: coordinates do not change.

• Batch operations when possible, for example one POST /api/trips for all queued orders.

• Validate coordinates before sending: latitude -90 to 90, longitude -180 to 180.

Security#

• Use HTTPS in production.

• Never share API keys. Rotate them periodically (see Get your API credentials).

• Monitor API usage for anything suspicious.