Rate Limiting

The Pathao Parcel API enforces rate limits to ensure fair usage and platform stability. Understanding and respecting these limits is essential for a reliable integration.

Default Limits

All API endpoints share a single rate limit window per partner.

100requests per minute per partner

This limit applies across all endpoints using the same API key. If you need a higher limit for your use case, contact your account manager.

Rate Limit Response Headers

Every API response includes headers that tell you the current state of your rate limit window.

Header	Type	Description
`X-RateLimit-Limit`	integer	The maximum number of requests allowed in the current window (e.g., 100).
`X-RateLimit-Remaining`	integer	The number of requests remaining in the current window.
`X-RateLimit-Reset`	unix timestamp	The UTC epoch timestamp (in seconds) when the current window resets.
`Retry-After`	integer	The number of seconds to wait before making another request. Only present on 429 responses.

429 Error Response Example

When you exceed the rate limit, the API returns a 429 Too Many Requests response with the standard error format and the Retry-After header indicating how long to wait.

429 Response

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705660800
Retry-After: 42

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Rate limit exceeded.",
    "details": []
  }
}

Best Practices

1Monitor the headers proactively. Check X-RateLimit-Remaining on every response. When it drops below 10%, start throttling your requests.
2Implement exponential backoff. When you receive a 429, wait for the duration specified in the Retry-After header. Add random jitter (0-1 second) to avoid thundering herd issues.
3Use a request queue. Instead of firing requests as fast as possible, use a queue with a controlled concurrency limit. This prevents burst patterns that trigger rate limits.
4Cache quotation responses. Delivery quotes are valid for 30 minutes. Cache quotation results to avoid unnecessary repeated calls.
5Use webhooks instead of polling. Rather than polling for status updates (which consumes your rate limit), register a webhook URL to receive real-time push notifications.

Rate Limit Response Headers

Every API response includes headers that tell you the current state of your rate limit window.

Header	Type	Description
`X-RateLimit-Limit`	integer	The maximum number of requests allowed in the current window (e.g., 100).
`X-RateLimit-Remaining`	integer	The number of requests remaining in the current window.
`X-RateLimit-Reset`	unix timestamp	The UTC epoch timestamp (in seconds) when the current window resets.
`Retry-After`	integer	The number of seconds to wait before making another request. Only present on 429 responses.

429 Error Response Example

When you exceed the rate limit, the API returns a 429 Too Many Requests response with the standard error format and the Retry-After header indicating how long to wait.

429 Response

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705660800
Retry-After: 42

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Rate limit exceeded.",
    "details": []
  }
}

Best Practices

1Monitor the headers proactively. Check X-RateLimit-Remaining on every response. When it drops below 10%, start throttling your requests.

2Implement exponential backoff. When you receive a 429, wait for the duration specified in the Retry-After header. Add random jitter (0-1 second) to avoid thundering herd issues.

3Use a request queue. Instead of firing requests as fast as possible, use a queue with a controlled concurrency limit. This prevents burst patterns that trigger rate limits.

4Cache quotation responses. Delivery quotes are valid for 30 minutes. Cache quotation results to avoid unnecessary repeated calls.

5Use webhooks instead of polling. Rather than polling for status updates (which consumes your rate limit), register a webhook URL to receive real-time push notifications.