Rate Limits & Errors

Rate Limits

Rate limits are applied per API key on a per-minute basis. Limits vary by plan:

Rate Limit Headers

Every API response includes headers to help you track your rate limit usage:

Example response headers

Rate Limit Exceeded

When you exceed the rate limit, the API returns a 429 Too Many Requests response with a retryAfter value indicating how many seconds to wait:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 45 seconds.",
    "retryAfter": 45
  }
}

Error Response Format

All errors follow a consistent format with a machine-readable code and a human-readable message:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message"
  }
}

Validation errors may include a details object with per-field error messages:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": {
      "url": "Must be a valid URL",
      "tags": "Tags feature requires Pro plan or higher"
    }
  }
}