Responses and errors

The API returns UTF-8 JSON. Use the HTTP status code to identify the request result, then read the response body for the data or error details.

Response format

A successful response sets status to ok and includes the result in dados:

{"status": "ok", "dados": {}}

An error response sets status to erro and describes the problem in mensagem:

{
  "status": "erro",
  "mensagem": "O parâmetro por_pagina deve ser um número inteiro de 1 a 100."
}

API messages are in Portuguese. Log them for troubleshooting, but use HTTP status codes for automated error handling because message wording may change.

HTTP status codes

Code	Meaning	Action
200	Operation completed.	Read dados.
201	Link created.	Store dados.id and dados.url_curta.
400	Missing, unknown, or invalid parameter.	Correct the request using the endpoint reference and error message.
401	Missing, invalid, expired, or revoked token.	Check the header and token status in the dashboard.
403	Access denied by the plan, account, or token.	Check your plan and access scope in Authentication.
404	Endpoint or resource not found within the token's scope.	Check the path, ID, and access to the link.
405	Incorrect HTTP method.	Use the method specified by the Allow header.
409	Link code already in use or reserved.	Choose a different code.
413	Request body larger than 16 KB.	Reduce the request body.
415	Unsupported content type.	Send JSON with Content-Type: application/json.
429	Daily quota or per-minute limit reached.	Wait for the duration specified in Retry-After.
500 or 503	Server error or service unavailable.	Wait before retrying.

Retrying requests

For 429, follow Retry-After. For temporary failures such as 500 or 503, increase the delay between attempts. Correct validation or authorization errors before retrying.

If a creation request receives no response, the link may still have been created. Search for its destination using List links before resending the request to avoid duplicates.

Repeating an update with identical values preserves the result. Repeating a deletion returns 404 if the link has already been removed.

Dates and times

Dates use YYYY-MM-DD, such as 2026-10-04. Timestamps use ISO 8601 with a time zone offset, such as 2026-10-04T14:32:10-03:00. Use the supplied offset when displaying or comparing timestamps.