Troubleshooting

What you see when something fails, what usually causes it and what to do. Look it up by the code the response carries in error.code: that is what does not change.

6 min readReviewed on October 25, 2026

First of all: read success, error.code and meta.requestId from the response. The error catalog explains every code in depth; this page gets you faster to the fix for the most common symptoms.

It will not let me in

Authentication and permissions
What you see	Most common cause	What to do
`401 AUTH_REQUIRED`	The `Authorization` header is missing, does not start with `Bearer` , or the token is in the URL or the body (it is ignored there).	Send `Authorization: Bearer hk_TU_API_KEY` on every request. See Authentication.
`401 AUTH_INVALID_KEY`	A typo when copying, uppercase letters in a key that is lowercase, a deleted or expired key, or a key from another environment.	Copy again the value Cloud showed when creating it. If you do not have it, create another key: the original cannot be recovered. See Your API key.
`403 ACCOUNT_NOT_ACTIVE`	The key’s organization is not active.	Write to support with the `requestId`.
`403 AUTH_IP_NOT_ALLOWED`	The key was created with a list of networks and you called from another one. Behind a NAT, a proxy or a cloud, the egress IP is often not the one you expect.	Compare `meta.clientIp` from the response with the key’s networks. The list cannot be changed: call from an allowed network or create another key.
`403 AUTH_SERVICE_NOT_ALLOWED`	The key does not have the endpoint’s service, or your organization turned it off.	Create a key with that service: the scope cannot be changed afterwards. See Requirements.
`403 AUTH_CAPABILITY_NOT_ALLOWED`	The endpoint needs an account capability the key lacks: `account` or `directory`.	Ask the owner of your organization for a key with that capability: only the owner creates keys. See Your API key.

They tell me to wait

Usage limits
What you see	Most common cause	What to do
`429 RATE_TPS_EXCEEDED`	You exceeded that endpoint’s limit for your organization. The ping allows 20 per minute; each endpoint states its own.	Wait the seconds in `Retry-After` and retry with exponential backoff. Read `RateLimit-Remaining` to slow down earlier. See Usage limits.
`429 RATE_DDOS_EXCEEDED`	Too many requests from the same IP, or the IP was cut off for 15 minutes for trying many different keys that do not authenticate.	Wait what `Retry-After` says. If you use several keys behind the same internet egress, check that none is miscopied or deleted.
`429 URLSHORTENER_LINK_QUOTA_EXCEEDED`	With a URL Shortener plan, you reached the daily creation quota.	`Retry-After` says how long until midnight in Colombia. If you need more, write to the sales team.

It will not let me create

Balance, plan and currency
What you see	Most common cause	What to do
`402 URLSHORTENER_INSUFFICIENT_FUNDS`	Your organization has no available balance to create the link. It was not created.	Top up the balance in Cloud and retry, ideally with the same `Idempotency-Key`.
`402 URLSHORTENER_SPEND_LIMIT_REACHED`	Creating the link would exceed a spending limit your organization set.	Topping up does not fix it: adjust the limit in Cloud.
`409 URLSHORTENER_CURRENCY_UNDEFINED`	Your organization has not chosen its currency yet.	Choose it in Cloud (it is chosen only once).
`409 URLSHORTENER_NOT_PRICED`	There is no URL Shortener price in your organization’s currency.	Retrying does not fix it. Write to support with the `requestId`.

My request is not valid

Malformed requests
What you see	Most common cause	What to do
`400 VALIDATION_INVALID_PARAMETER`	A field with an invalid format, a field that does not exist (for example `url` or `alias`, from the previous contract) or malformed JSON.	Compare your body with the endpoint’s page in the reference. The message names the field.
`400 URL_INVALID`, `URL_SCHEME_NOT_ALLOWED`, `URL_BLOCKED_HOST`	The destination is not an absolute `http` or `https` URL, points to an internal address or already is a short link.	Use a full public URL. See the URL Shortener guide.
`409 ALIAS_TAKEN`, `ALIAS_RESERVED`, `ALIAS_RETIRED`	The alias already exists on that domain, is a reserved word or a brand on a shared domain, or belonged to a deleted link of yours.	Choose another alias, or restore the deleted link if it was yours.
`422 IDEMPOTENCY_KEY_REUSED`	You used an `Idempotency-Key` with a body different from the first time.	One key identifies one operation: use a new key. See Idempotency.
`404 NOT_FOUND`	The route does not exist: a typo in the path, another version or an endpoint that is not in the reference.	Check that you call `https://developers.hablame.co/api/v6/...` and that the path matches the reference.
`501 NOT_IMPLEMENTED`	The route is reserved but no service behind it yet.	Do not retry. Use only the endpoints in the reference.
`405 METHOD_NOT_ALLOWED`	You used a method the route does not support. The Storage queries are `GET` only.	Use the method the reference states.

It fails on our side

Service failures
What you see	Most common cause	What to do
`503 SERVICE_UNAVAILABLE`	A service we depend on is not responding, or is handling too many requests at once and rejects yours immediately.	Retry after `Retry-After` with a random jitter. If it persists, check the status.
`504 GATEWAY_TIMEOUT`, `INFRA_DB_QUERY_TIMEOUT`	A service took too long, for example on a very broad query.	Retry with exponential backoff and, if you can, narrow the date range or the filter.
`500 INTERNAL_SERVER_ERROR`	Something went unexpectedly wrong on our side.	Retry once. If it repeats, write to support with the `requestId`.

On a 5xx when creating a link, always retry with the same Idempotency-Key: that way, if the first one did get created, you receive that link and it is not charged twice.

The product does not behave as I expect

El enlace corto da 404: An active link stops redirecting if its expiresAt has passed, if its domain is suspended, released or unverified (domainStatus), or if Hablame blocked it (status: blocked). Query the link with GET /urlshortener/links/{domain}/{code}.
Las visitas no coinciden: A background process consolidates visits: one can take from seconds to a few minutes to appear. Bots and the previews from social networks and chat apps are not counted.
No me llegan los webhooks: Check that your URL responds with a 2xx code and does not use redirects, and that you verify the signature over the unmodified body. See Delivery and retries.
Mi cliente se rompe con un campo nuevo: The API adds fields without notice; existing ones do not change type. Your client must ignore what it does not know. See the response envelope.
Llamo desde el navegador: Do not do it with your real key: anyone who opens the browser tools would see it. Make the call from your server.

What to gather before writing to support

The meta.requestId from the response (it is also in the X-Request-Id header). It is the most useful: with it we find your exact request.
The error.code and the HTTP status.
The endpoint and the method you called, and the time in UTC.
Your organization name.

Do not send your full API key, an SMPP password or a signing secret. Your organization name is enough to identify your account.

For technical questions, email developers@hablame.co. If you have a production incident, message us on WhatsApp at +57 319 660 0002, 24/7.