Errors & rate limits

The error envelope

Every error returns the same JSON shape, with a stable machine-readable code and a human-readable message:

{
  "error": {
    "code": "not_found",
    "message": "The requested resource could not be found."
  }
}

Branch on code, not on message. Messages are written for humans and may be reworded; codes are part of the contract.

Validation failures add an errors object keyed by field name, each holding an array of messages:

{
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "errors": {
      "destination_url": ["The destination url field must be a valid URL."],
      "expires_at": ["The expires at field must be a date after now."]
    }
  }
}

Status codes

Success

Errors

Other HTTP failures fall back to the generic code http_error.

Codes in practice

401 vs 403

These two are easy to confuse and mean quite different things:

• 401 unauthenticated — we could not identify you at all. The Authorization header is missing, malformed, or the key has been revoked or has expired. Check the credential.
• 403 forbidden — we know exactly who you are, and this key is not allowed to do that. The key was issued without the required scope. Generate a new key with the scope included; scopes cannot be added to an existing key.

402 payment_required

The API requires an active plan. This check runs after authentication, so a bad key returns 401 even on an unsubscribed account.

Access is granted for a lifetime purchase, a running trial, or a live subscription. A subscription that has lapsed into past_due — after a card failure, for example — returns 402 until billing is resolved.

404 not_found

Returned both for a resource that does not exist and for one that exists on another account. The API deliberately does not distinguish between the two, so it cannot be used to probe for valid ids belonging to other customers.

If a 404 is unexpected, check that you are using the resource’s UUID and not a numeric id or a slug.

422 validation_error

The most common cause of a 422 on writes:

{ "message": "not-a-domain is not a valid domain name. Ensure your domain name is valid" }

Rate limits

Requests are limited to 60 per minute, counted per API key.

Two keys on the same account get independent budgets, and keys are never throttled by unrelated traffic sharing an egress IP address — which matters if you call the API from a NAT gateway, a CI runner, or a serverless platform.

Reading your budget

Successful responses carry the current state of your bucket:

When you exceed it

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests."
  }
}

The window is a rolling minute. Back off and retry — an exponential backoff starting around one second, with jitter, is a reasonable default.

Staying under the limit

• Page in bulk. Use per_page=100 on list endpoints rather than making seven times as many calls at the default of 15.
• Prefer /stats over /clicks when you only need counts. One aggregated call replaces paging through thousands of individual clicks.
• Use webhooks instead of polling. Subscribing to link.clicked removes the need to poll for new clicks at all, which is what most rate-limit pressure turns out to be.
• Serialise your workers. If several processes share one key, they share one 60/minute budget. Give each its own key, or put them behind a single rate-limited queue.