Error catalog

We did not see a Bearer token in your request. Every API v6 call needs an API key in the Authorization header: without it we cannot tell which organization is calling.

The API key you sent is not recognized. Three situations produce this code: a key with the wrong format, a key that was rotated or revoked, or a key past its expiration date.

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

This key is not allowed to call the service behind this endpoint. Keys can be restricted to specific services so that a leaked or misused key can only do what it was allowed to.

Reserved code, kept as a bridge for callers migrating from v5. API v6 does not 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, usually because it was suspended or closed. While that lasts, every endpoint rejects calls, including the diagnostic ones.

Your organization is under a full block. Every call is rejected, including read-only ones, until the block is lifted.

Your organization is in read-only mode. Requests that only read information (GET, HEAD, OPTIONS) keep working, but any call that creates or modifies data is rejected.

Your API key authenticated correctly, but we could not load the organization it points to. This is a data problem on our side, not in your request.

Your source IP produced an unusually high volume of requests in the last minute. This protection is designed to absorb attack and scanner traffic; legitimate integrations rarely get close to the limit.

You sent more requests to this endpoint than your organization quota allows in the current window. Each endpoint has its own quota: hitting the wall on one does not affect the others.

The Idempotency-Key is empty, too long, or contains characters outside the allowed set. It accepts 1 to 255 characters from A-Z a-z 0-9 _ -.

You sent the same idempotency key while the original request is still being processed. It does not run twice: the second one waits.

You used an idempotency key that already exists, with a different body. It is almost always a client bug: one key identifies one operation, not several.

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).

The code sent to GET /api/v6/tools/countries/{code} does not match any country in the catalog. The parameter expects a two-letter ISO 3166-1 alpha-2 code.

One of the services we depend on was temporarily unreachable when your request arrived. It is a problem on our side, not with what you sent.

Same scenario as the previous one, with a different internal piece. The failure is transient and recovers on our side with no change on yours.

An internal query took longer than we allow before returning a response, so we cut it off instead of leaving your client waiting indefinitely.

We could not parse your request. The most common causes are malformed JSON in the body, a Content-Type header that does not match the payload, or a path with invalid characters.

Generic 401 returned before the authentication logic could give you a more specific code. When you see it, the request was rejected in a layer earlier than API key validation.

The request authenticated correctly but is not allowed to access this resource. When the cause is a known organization state you get an ACCOUNT_* code instead; this generic one is the fallback.

The path you requested does not exist in this API. We also return this code, deliberately indistinguishable from a normal 404, for requests whose Host header is not on our allowed list, so the API surface cannot be probed by guessing hostnames.

The path exists but does not accept the HTTP method you used, for example a POST to a read-only endpoint. The response includes an Allow header with the valid methods.

Generic 429. When the limit you hit is one of ours we return RATE_DDOS_EXCEEDED or RATE_TPS_EXCEEDED instead, which carry more context. Branch on the specific ones when present.

Something went unexpectedly wrong while processing 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 service we depend on is not responding. The INFRA_* codes are more specific when we can name the failing component; this is the fallback when we cannot.

A service we depend on took too long to respond. When the slow component was the database you will see INFRA_DB_QUERY_TIMEOUT instead, which means the same with more context.