Error catalog

We didn't see a Bearer token on your request. Every call to the v6 API needs an API key in the Authorization header. Without it we can't tell which organization is asking.

The API key you sent isn't recognised. Three things produce this code: a key with the wrong shape, a key that was rotated or revoked, or a key that has reached its expiration date.

Every API key is attached to a cost center so usage can be billed and reported correctly. The cost center attached to this key is currently disabled.

This key isn't scoped to call the product behind this endpoint. Keys can be restricted to specific products (SMS, WhatsApp, e-mail, …) so a leaked or misused key can only do what it was meant to.

Reserved code, kept as a bridge for callers migrating from v5. The v6 API doesn't use the source-IP override mechanism that produced this error, so you should not see it on v6 traffic.

Your organization is not in an active state right now, typically because it has been suspended or closed. While that's the case, every endpoint will reject calls, even diagnostic ones.

Your organization is currently subject to a hard block from our side. Every call is rejected (including read operations) until the block is removed.

Your organization is in read-only mode. Requests that only fetch information (GET, HEAD, OPTIONS) still succeed, but anything that creates or changes data is rejected.

Your API key authenticated correctly, but we couldn't load the organization it points to. This indicates an internal data issue on our side, not a problem with your request.

Your source IP has produced an unusually high volume of requests in the past minute. This protection is meant to absorb attack and scanner traffic; legitimate integrations very rarely come close to it.

You've sent more requests to this specific endpoint than your organization's quota allows within the current window. Each endpoint has its own quota; hitting the wall on one doesn't affect the others.

One of the services we rely on internally was temporarily unreachable when your request arrived. This is a problem on our side, not in your request.

Same shape as the previous one, for a different piece of our internal infrastructure. The failure is transient and recovers on our side without any change on yours.

An internal query took longer than we allow before returning a response, so we cut it short rather than leaving your client hanging.

The url you sent isn't a valid absolute URL: we couldn't parse a scheme and host out of it.

The destination uses a scheme we don't shorten (e.g. javascript:, data:, ftp:, file:).

The destination URL is longer than the 2048-character maximum.

The destination points at a private/reserved address or an internal hostname (e.g. 127.0.0.1, 10.0.0.0/8, localhost). We block these so short links can't be used to reach internal endpoints.

The alias isn't 3-32 characters of lowercase letters, digits, hyphen or underscore.

Another link on the same domain already uses that alias. Codes are unique per domain.

The alias collides with a reserved word (e.g. api, stats, admin, docs).

expiresAt couldn't be parsed as an ISO-8601 date-time, or it is in the past.

No link with that domain and code belongs to your account. For privacy we return 404 for links owned by other accounts too, so we don't disclose their existence.

The PATCH body had none of the updatable fields (active, expiresAt, longUrl).

We couldn't allocate a unique random code after several attempts. This is rare.

The statistics window is inconsistent: from after to, a range above the cap (1 year for day, 31 days for hour), or hour requested outside the ~90-day hourly retention.

The domain you requested isn't a platform-global domain nor one owned by your account (or your account has no default domain configured).

We could not parse your request. The usual culprits are malformed JSON in the body, a Content-Type header that doesn't match the payload, or a path with invalid characters.

Generic 401 returned by the framework before our authentication logic could give you a more specific code. When you see this code, the request was rejected at a layer above the API key check.

The request authenticated correctly but isn't allowed to access this resource. Whenever the cause is a known organization state, you'll receive an ACCOUNT_* code instead. This generic one is the fallback.

The path you requested doesn't exist on this API. We also return this code (intentionally indistinguishable from a normal 404) for requests whose Host header isn't on our allowlist, so the API surface can't be probed by spelling guesses.

The path exists but it doesn't accept the HTTP method you used (for example, sending a POST to a read-only endpoint). The response includes an Allow header listing the methods that are valid for that path.

Generic 429. Whenever the limit you hit is one of ours, we return RATE_DDOS_EXCEEDED or RATE_TPS_EXCEEDED instead, since those carry richer context. Branch on the specific codes when present.

Something unexpected went wrong on our side while handling your request. The full trace is stored against the same meta.requestId we returned, so we can investigate without you having to reproduce the failure.

A backing service we depend on isn't responding. The INFRA_* codes above are more specific when we can name the failing component; this one is the fallback otherwise.

An upstream we depend on took too long to respond. When the slow component was the database, you'll see INFRA_DB_QUERY_TIMEOUT instead, which carries the same meaning with more context.