Error Codes

When a request fails, the API returns a structured error response with an error code, a human-readable message, and, where applicable, a details array pinpointing specific field issues.

Error Response Format

Every error response follows a consistent JSON structure. The code field contains a machine-readable identifier you can use for programmatic error handling, while message provides a human-readable explanation.

Error Response

Complete Error Code Reference

The table below lists every error code the API may return, along with guidance on whether the request can be retried and how to resolve the issue.

Code	HTTP Status	Description	Resolution
`VALIDATION_ERROR`	400	One or more request fields are invalid.	Check the 'details' array in the response for specific field errors.
`INVALID_COORDINATES`	400	Coordinates are outside the serviceable area.	Ensure latitude/longitude values are within Dhaka metropolitan area boundaries.
`UNAUTHORIZED`	401	Missing or invalid API key.	Include a valid X-API-Key header. Check your API key in the dashboard.
`FORBIDDEN`	403	Partner account is inactive or suspended.	Contact your account manager to reactivate your integration.
`NOT_FOUND`	404	The requested order was not found.	Verify the order_id or partner_reference_id is correct.
`INVALID_STATUS_TRANSITION`	409	The requested action is not allowed for the current order status.	Check the order status before attempting cancel or retry operations.
`IDEMPOTENCY_CONFLICT`	409	The idempotency key was used with different request parameters.	Use a unique X-Idempotency-Key for each unique order request.
`RATE_LIMIT_EXCEEDED`	429	Too many requests. Rate limit exceeded.	Wait for the duration specified in the Retry-After header before retrying.
`INTERNAL_ERROR`	500	An unexpected server error occurred.	Retry the request with exponential backoff. Contact support if persistent.
`SERVICE_UNAVAILABLE`	503	The service is temporarily unavailable.	Retry after a short delay. Check status.pathao.com for outage info.

Error Handling Best Practices

1Check the error code, not the message. Error messages may change over time. Always branch your logic based on the code field.
2Retry only retryable errors. For errors marked as retryable (429, 500, 503), implement exponential backoff with jitter. Never retry 4xx client errors other than 429.
3Parse the details array. For VALIDATION_ERROR responses, iterate over the details array to surface field-level errors to your users or logs.
4Log the full response. Always log the complete error response including headers for debugging. The X-Request-Id header is especially useful when contacting support.
5Handle unknown codes gracefully. New error codes may be added in the future. Treat any unrecognized code as a non-retryable error and log it for investigation.

Error Response Format

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more request fields are invalid.",
    "details": [
      {
        "field": "receiver_phone",
        "message": "Must be a valid Bangladeshi mobile number (01XXXXXXXXX)."
      },
      {
        "field": "pickup_latitude",
        "message": "Required field is missing."
      }
    ]
  }
}

Error Response

Complete Error Code Reference

The table below lists every error code the API may return, along with guidance on whether the request can be retried and how to resolve the issue.

Code	HTTP Status	Description	Resolution
`VALIDATION_ERROR`	400	One or more request fields are invalid.	Check the 'details' array in the response for specific field errors.
`INVALID_COORDINATES`	400	Coordinates are outside the serviceable area.	Ensure latitude/longitude values are within Dhaka metropolitan area boundaries.
`UNAUTHORIZED`	401	Missing or invalid API key.	Include a valid X-API-Key header. Check your API key in the dashboard.
`FORBIDDEN`	403	Partner account is inactive or suspended.	Contact your account manager to reactivate your integration.
`NOT_FOUND`	404	The requested order was not found.	Verify the order_id or partner_reference_id is correct.
`INVALID_STATUS_TRANSITION`	409	The requested action is not allowed for the current order status.	Check the order status before attempting cancel or retry operations.
`IDEMPOTENCY_CONFLICT`	409	The idempotency key was used with different request parameters.	Use a unique X-Idempotency-Key for each unique order request.
`RATE_LIMIT_EXCEEDED`	429	Too many requests. Rate limit exceeded.	Wait for the duration specified in the Retry-After header before retrying.
`INTERNAL_ERROR`	500	An unexpected server error occurred.	Retry the request with exponential backoff. Contact support if persistent.
`SERVICE_UNAVAILABLE`	503	The service is temporarily unavailable.	Retry after a short delay. Check status.pathao.com for outage info.

Error Handling Best Practices

1Check the error code, not the message. Error messages may change over time. Always branch your logic based on the code field.

2Retry only retryable errors. For errors marked as retryable (429, 500, 503), implement exponential backoff with jitter. Never retry 4xx client errors other than 429.

3Parse the details array. For VALIDATION_ERROR responses, iterate over the details array to surface field-level errors to your users or logs.

4Log the full response. Always log the complete error response including headers for debugging. The X-Request-Id header is especially useful when contacting support.

5Handle unknown codes gracefully. New error codes may be added in the future. Treat any unrecognized code as a non-retryable error and log it for investigation.