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.

Some endpoints require, besides the service, an explicitly granted capability. In the URL shortener, creating, editing, deleting and restoring links requires urlshortener.write: a key with the urlshortener service and without that capability lists and reads links, statistics, the overview, the domains and the pricing, and gets this code when it tries to write. The account and organization endpoints require account or directory, and there the message is a different one: «This API key lacks the capability required for this endpoint. Capabilities are set when a key is issued and cannot be added later: use a key that has it, or issue a new one that includes it from the customer portal (Developers -> API keys).»

This key has a list of allowed networks (single IPs or CIDR blocks, IPv4 or IPv6) and the request came from an IP that is in none of them. The key is valid and your organization is active: the only thing that does not match is the origin. The IP we saw you calling from comes in meta.clientIp of the same response.

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.

The per-source-IP guard fired, for one of two reasons. First: your IP produced an unusually high volume of requests in the last minute; legitimate integrations rarely get close to the limit. Second: 60 different API keys that do not authenticate arrived from your IP within one minute (keys that do not exist, or were revoked or expired), which is the footprint of someone guessing keys; the IP is then cut off for 15 minutes, and during that time it gets this 429 even if the key you send is valid. Both count IPv6 addresses by their /64 block: every address in the same /64 shares the limit and the cut-off.

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 URL shortener overview and statistics also have a cost quota: each query spends units according to the days and sections it asks for, and the overview is computed at most twice at once per organization. And URL shortener bulk creation has a per-link limit (2,100 per minute per organization): a batch that does not fit is rejected whole, without creating or charging anything.

The Idempotency-Key is too long or contains characters outside the allowed set. It accepts 1 to 255 characters from A-Z a-z 0-9 _ -. Nothing was done: nothing was created or charged.

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 your organization already used, with a different body. Nothing new was created or charged. It is almost always a client bug: one key identifies one operation, not several.

The destination URL isn't a valid absolute URL (we couldn't parse a scheme and host), or it carries something that would make a reader see a destination other than the real one: a user or password before the domain (https://bank.com@other.com), a domain with accents, ñ or letters from other alphabets —also written as xn--—, or invisible characters. The message says which one it was.

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), or it already is a short link: one of our domains or a shortener such as bit.ly, tinyurl.com or t.co. We block these so short links can't be used to reach internal endpoints or to hide the final destination behind a chain of hops.

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

Another link on the same domain already used that alias, whether it still exists or not: links deleted or expired 90 or more days ago are archived, and their code stays reserved forever. Codes are unique per domain and are never released.

The alias collides with a reserved word (e.g. api, stats, admin, docs), or —on a platform domain, which every organization shares— it looks like the name of a brand, a bank, a payment method or a public entity (bancolombia-seguro, pago-pse, dian). A single impersonation link on a shared domain makes security filters flag it, and then everyone’s links stop opening.

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 (longUrl, status, expiresAt).

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

The statistics window is not valid: from or to are not YYYY-MM-DD, from is after to, the window exceeds the cap (366 days with day, 31 days with hour) or the granularity is neither day nor hour.

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 domain is one of your organization’s own, but it is not verified yet. Until it is, it cannot be used to create links: it might not point to the platform yet, and the link would be born broken.

You already used that alias on a link you deleted. The code of a deleted link is never released —a short URL you already handed out cannot reappear with another destination—, so no other link can be created with it. But that link can be restored for 90 days after you deleted it; after that it is archived and the alias returns ALIAS_TAKEN.

Hablame blocked this link (status: blocked), for example after an impersonation report. A blocked link does not redirect and cannot be edited, deleted or restored through the API.

With an active URL shortener plan, creating links is not charged, and that is why there is a creation quota per Colombia day (100,000, unless you agreed another one). Your organization already used it today, or the batch you sent does not fit in what is left: in bulk creation every link counts, and a batch that does not fit whole is rejected whole, without creating any. Without a plan there is no daily quota: what stops it is the balance.

Bulk creation accepts up to 1,000 links per request, and the one you sent has more. None was created and nothing was charged.

Creating a link is charged on creation, and your organization has no available balance to cover it (or it reached a spend limit it configured itself). The link was not created. In bulk creation the price of all the valid links is reserved at once: without balance for all of them, none is created.

Your organization has balance, but creating this link would exceed a spend limit it configured itself: for the whole organization, for the URL shortener, for a cost center, for a user or for this API key. The link was not created.

We found no URL shortener price for your organization’s currency, so we cannot charge the operation and we do not perform it. It is a configuration problem on our side, not in your request.

An organization’s currency is chosen once, when its setup is finished, and everything it consumes is charged in it. Until it has one, we cannot price the operation and we do not perform it.

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. In the URL shortener (the link list, its statistics and the overview) the database itself cuts it, and it happens with very large queries for organizations with many links: a long range, many sections or a broad search.

A query parameter has a value that does not exist, or the body carries an unknown field, a wrong type or is not JSON. The message says which one and what it accepts.

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, or is handling too many requests at once: each service has its own cap of simultaneous requests at the edge, and when it is full the request is rejected immediately with Retry-After instead of waiting. 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.