Rate Limits & Error Handling¶
Ruby enforces predictable sliding-window rate limits and standardized error responses across the Public Developer REST API to ensure high reliability and fair platform utilization.
1. Rate Limits¶
API rate limits are evaluated per active API key using a high-precision sliding-window token bucket. Request limits are determined by your organization's subscription plan:
| Subscription Tier | API Access | Rate Limit (Requests / Min) |
|---|---|---|
| Free | Not Included | 0 (Requires Pro or higher) |
| Pro | Included | 60 requests / minute |
| Business | Included | 180 requests / minute |
| Enterprise | Included | 600 requests / minute (Custom higher limits available) |
Plan API Entitlements
Developer API access is available starting on the Pro tier. Requests made with API keys belonging to an organization on the Free tier will receive 403 Forbidden (Developer API access is not available on your plan. Please upgrade to Pro or Business.).
2. Rate Limit Headers¶
Every response from the Public Developer API—including successful calls and rate-limited calls—supplies real-time rate limit headers:
| Header | Type | Description | Example |
|---|---|---|---|
X-RateLimit-Limit |
integer |
Your maximum allowed request capacity per 60-second window. | 60 |
X-RateLimit-Remaining |
integer |
The number of remaining request tokens available in the current window. | 45 |
X-RateLimit-Reset |
integer |
Unix timestamp in seconds (UTC) when the token bucket fully replenishes. | 1731024060 |
Retry-After |
integer |
(Returned only on 429) The number of seconds you must wait before retrying. |
1 |
Rate Limit Exceeded (HTTP 429)¶
When your request burst exceeds your allowed capacity, Ruby immediately responds with 429 Too Many Requests:
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1731024060
Retry-After: 1
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded",
"param": null
}
}
Retry Best Practice: Exponential Backoff & Jitter
When your application encounters 429 Too Many Requests, inspect the Retry-After header value and wait at least that many seconds before retrying. For resilient automated integrations, apply exponential backoff with randomized jitter to prevent thundering herd spikes.
3. Standardized Error Response Envelope¶
All error responses from the Developer REST API (/v1/*) conform to a strict, standardized JSON error envelope:
Error Object Attributes¶
| Field | Type | Description |
|---|---|---|
code |
string |
A machine-readable, uppercase alphanumeric string identifying the error category. |
message |
string |
A human-readable description explaining the reason for the error. |
param |
string | null |
The specific request body parameter or query parameter that caused the error (e.g. destination_url, domain). Populated primarily on validation errors (422). |
4. Validation Errors (HTTP 422)¶
If a request payload fails schema validation, required fields are missing, or domain constraints are violated, Ruby returns 422 Unprocessable Entity with param set to the offending attribute:
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Custom aliases are not permitted on default platform domains",
"param": "custom_alias"
}
}
5. HTTP Status Codes & Error Codes Reference¶
The following table lists all possible HTTP status codes and their corresponding machine-readable error codes:
| HTTP Status | Error Code (code) |
Description & Typical Cause |
|---|---|---|
400 Bad Request |
BAD_REQUEST |
Malformed JSON body or invalid syntax. |
401 Unauthorized |
UNAUTHORIZED |
Missing authentication, invalid token format, expired HMAC timestamp, or invalid HMAC signature. |
403 Forbidden |
FORBIDDEN |
Missing required API scope, or the organization plan does not include API access. |
403 Forbidden |
QUOTA_EXCEEDED |
Monthly link creation quota or retention limit exceeded for your subscription plan. |
404 Not Found |
NOT_FOUND |
The specified short link, campaign group, or resource does not exist. |
409 Conflict |
CONFLICT |
Resource conflict (e.g. custom alias or short code already in use on the target domain). |
422 Unprocessable Entity |
VALIDATION_ERROR |
Schema validation error (e.g. invalid URL syntax, missing required fields, or disallowed parameter combinations). param identifies the failing field. |
429 Too Many Requests |
RATE_LIMIT_EXCEEDED |
Rate limit capacity exceeded. Inspect the Retry-After header. |
500 Internal Server Error |
INTERNAL_SERVER_ERROR |
An unexpected server error occurred. |