Skip to content

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": {
    "code": "NOT_FOUND",
    "message": "Link not found",
    "param": null
  }
}

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.