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 are restricted to specific services so that a leaked or misused key can only do what it was allowed to. Each service is granted in full: with the URL shortener, the key also creates and deletes links; with Storage, it also views and downloads the files. Without the service, the key cannot use any of its endpoints.

The account and organization endpoints require an explicitly granted capability: account (balance and billing) or directory (organization data, cost centers and users). They are the only capabilities: within a service there are no partial permissions, because the service is granted in full.

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.

There is no file with that id your organization can see. It is the SAME answer, on purpose, for a file that never existed, one from another organization, one already deleted or being deleted, and a malformed id: that way nobody can find out which files exist by trying identifiers.

The cursor was altered, belongs to another organization, was requested with other filters or is more than 24 hours old. A cursor only works to continue the SAME list, with the same filters, for a short time.

A service or file type that does not exist, a scope without service, a date that cannot be read, a reversed or too long range (up to 400 days per day or month, up to 7 days per hour), a group other than day, month or hour, a limit outside 1 to 200 or minutes outside 1 to 60. The message says which, in Spanish, with the internal name of the parameter (desde is from, hasta is to, agrupar is group, limite is limit).

We strip everything that is not a digit from the number (spaces, hyphens or the + sign) and count what is left: there must be between 7 and 18 digits. Outside that range we do not place the call and we charge nothing. The automated calls service is not open in the public reference yet; the code is documented so that its error.type link leads to this explanation.

You generate the verification code, and Hablame does not make one up: it must come in the request, because it is the same one your system will later compare with what the person types. Without it no call is placed and nothing is charged.

The code read out in the call only accepts digits, up to 10. A letter, a space or a longer code is rejected before calling.

In the message, {otp} marks the place where the code is read out. With two markers there is no way to know which one you meant, and reading the code twice is worse than not calling, so we reject the message.

The voice needs a text to say, from 1 to 4,000 characters. An empty or longer message is rejected before calling.

Before calling we reserve what the call may cost. If your organization has no available balance, or no active billing account, the call is not placed and nothing is charged. The name includes TTS because it is the same code that already existed for the balance missing when generating the voice of a call.

We do not dial without knowing the cost. If there is no rate for the destination of the call, it is not placed and nothing is charged. It is a configuration problem on our side, not in your request.

The balance is reserved in one currency and charged in the same one. If the destination rate is in a currency different from your organization’s, we reject the call instead of converting between currencies. The call is not placed and nothing is charged.

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.

The service handling the route answered 409 Conflict without a code of its own, so the response carries this generic one. The conflicts we know about have their specific code, such as ALIAS_TAKEN or DOMAIN_NOT_VERIFIED: branch on those when present. The message carries the service explanation when it sends one; otherwise, a general text that points to this page.

The service handling the route answered 422 Unprocessable Entity without a code of its own, so the response carries this generic one. The cases we know about have their specific code, such as IDEMPOTENCY_KEY_REUSED: branch on those when present. The message carries the service explanation when it sends one; otherwise, a general text that points to this page.

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.

The route is reserved in the API, but no service behind it can serve it yet. The message in the response says why. It is neither a temporary failure nor an error in your request.

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.

The service handling the route answered 502 Bad Gateway without a code of its own, so the response carries this generic one. The failure is on our side, not in your request. The message carries the service explanation when it sends one; otherwise, a general text that points to this page.

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.