API referenceGetting started
Rate limiting
Request limits per organization, the rate limit headers, and what to do when you hit a limit.
Default rate limits
By default, every organization is allowed 1,000 requests per minute, and 40,000 requests per day. If your organization's needs exceed these limits, please contact us at developers@mothership.com.
Two endpoints have their own, lower limits on top of these.
| Endpoint | Limit |
|---|---|
| Create a quote | 100 quotes per minute until the organization has created 500 quotes, then 10 per minute. The count of 500 resets four hours after the first quote in the window. |
| Create a shipment | 100 shipments per minute. |
These endpoint limits only count requests that pass validation, so a malformed request doesn't use up your quota. Sandbox requests are counted separately from production.
Response headers
Every API response includes the following rate limiting headers. On the two endpoints above, they describe the endpoint limit.
| Header | Description |
|---|---|
X-RateLimit-Limit | The maximum number of requests for the current time window. |
X-RateLimit-Remaining | The number of requests remaining for the current time window. |
X-RateLimit-Reset | A unix timestamp, in seconds, of when the request counter resets. |
Limit exceeded
If you exceed your rate limit, the API will respond with HTTP status code 429 and the header Retry-After. Retry-After is the length of the window you exceeded, in seconds: 60 for a per-minute limit and 86400 for the daily limit. To wait no longer than needed, wait until the time in X-RateLimit-Reset.
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1773939660{
"code": 429,
"type": "RATE_LIMIT_EXCEEDED",
"message": "You have reached your minutely limit. Please try again in the next minute."
}| Limit | Message |
|---|---|
| Per minute | You have reached your minutely limit. Please try again in the next minute. |
| Per day | You have reached your daily limit. Please try again in the next day. |
| Quotes | You have hit your quote rate limit |
| Shipments | You have hit your shipping rate limit |