Limites, quotas e erros
Limites de pedidos, quota de downloads e os códigos de erro da API.
Pedidos por minuto
| Limite | |
|---|---|
| Com token | 60 pedidos por minuto, por token |
| Sem token | 20 pedidos por minuto, por endereço IP |
O limite vale para todos os endpoints de /v1/public em conjunto. Cada
resposta traz os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e
X-RateLimit-Reset. Acima do limite, a API responde 429 RATE_LIMITED,
com o cabeçalho Retry-After (segundos até poderes tentar de novo):
{ "error": "RATE_LIMITED", "message": "Demasiados pedidos. Tenta novamente dentro de 42 s." }Respeita o Retry-After
Quando recebes um 429, espera os segundos indicados em Retry-After antes do
pedido seguinte, em vez de repetir logo.
Quota de downloads
Pedir a ligação de um ficheiro usa a mesma quota do site e das integrações:
| Downloads em 24 horas | |
|---|---|
| Sem token (contados por endereço IP) | 3 |
| Com token de uma conta | 5 |
- Repetir o mesmo logótipo nas 12 horas seguintes não conta de novo (por exemplo, o SVG e depois o PNG). Um ZIP conta uma vez.
- Pesquisar, ver os detalhes de um logótipo e as cores das marcas não conta.
- Cada download deixa de contar 24 horas depois de feito.
- Com a quota cheia, não podes descarregar nada, nem um logótipo repetido, até a quota reiniciar.
A resposta de cada download traz o estado da quota:
"quota": { "unlimited": false, "used": 1, "limit": 5, "remaining": 4, "resetAt": "2026-10-15T09:00:00.000Z" }Com a quota cheia, a API responde 403 DOWNLOAD_LIMIT_REACHED, com o
âmbito (anonymous ou daily), o limite e quando voltas a ter downloads:
{
"error": "DOWNLOAD_LIMIT_REACHED",
"message": "Atingiste o teu limite diário de downloads. Tenta novamente mais tarde.",
"scope": "daily",
"limit": 5,
"resetAt": "2026-10-15T09:00:00.000Z"
}Vê também quotas e downloads.
Outros limites
| Limite | Se passares | |
|---|---|---|
| Paletas por conta | 100 | 409 PALETTE_LIMIT |
| Cores por paleta (ou por gradiente) | De 2 a 10 | 400 INVALID_REQUEST |
| Nome de uma paleta | 60 caracteres | 400 INVALID_REQUEST |
| Propostas de logótipos por conta | 10 em 24 horas | 429 PROPOSAL_LIMIT_REACHED |
| Ficheiro de uma proposta | 5 MB; SVG, PNG, JPEG ou WEBP | 413 FILE_TOO_LARGE ou 415 UNSUPPORTED_FILE |
| Tokens activos por conta | 20 | Ao criar o token no site |
Resultados por página (pageSize) | 50 | 400 INVALID_REQUEST |
Formato dos erros
Todos os erros vêm em JSON, com um código fixo em error (para o teu código
decidir o que fazer) e uma mensagem em português em message (para mostrar a
pessoas):
{ "error": "LOGO_NOT_FOUND", "message": "Logótipo não encontrado." }Alguns erros trazem campos extra, como scope, limit e resetAt no
DOWNLOAD_LIMIT_REACHED. Quando os parâmetros ou o corpo do pedido não são
válidos, issues diz que campos falharam:
{
"error": "INVALID_REQUEST",
"message": "Pedido inválido.",
"issues": [{ "field": "body.colors", "message": "Uma paleta precisa de pelo menos 2 cores" }]
}Códigos de erro
| Estado | Código | Significado |
|---|---|---|
| 400 | INVALID_REQUEST | Parâmetros ou corpo do pedido inválidos (vê issues) |
| 400 | FORMAT_MISMATCH | O assetId indicado não é do formato pedido |
| 400 | COMPANY_NAME_REQUIRED | Proposta sem companyName nem companySlug |
| 400 | LOGO_COMPANY_MISMATCH | O logótipo indicado na proposta não é da empresa indicada |
| 400 | FILE_REQUIRED | Proposta sem o ficheiro (file) |
| 400 | EMPTY_FILE | O ficheiro da proposta está vazio |
| 400 | UNSAFE_SVG | O SVG tem scripts ou eventos: exporta-o de novo sem conteúdo interactivo |
| 401 | TOKEN_REQUIRED | O endpoint precisa de token |
| 401 | INVALID_TOKEN | Token inválido |
| 401 | TOKEN_REVOKED | Token revogado |
| 401 | TOKEN_EXPIRED | Token expirado |
| 403 | INSUFFICIENT_SCOPE | O token não tem a permissão necessária |
| 403 | FORBIDDEN | Só o dono pode alterar ou apagar esta paleta |
| 403 | DOWNLOAD_LIMIT_REACHED | Quota de downloads cheia (vê resetAt) |
| 404 | COMPANY_NOT_FOUND | Empresa não encontrada |
| 404 | LOGO_NOT_FOUND | Logótipo não encontrado |
| 404 | VARIANT_NOT_FOUND | Variante não encontrada neste logótipo |
| 404 | FORMAT_NOT_AVAILABLE | O logótipo não tem esse formato |
| 404 | ASSET_NOT_FOUND | O assetId não existe neste logótipo |
| 404 | PALETTE_NOT_FOUND | Paleta não encontrada (ou é privada de outra pessoa) |
| 409 | PALETTE_LIMIT | A conta já tem 100 paletas |
| 413 | FILE_TOO_LARGE | O ficheiro passa dos 5 MB |
| 413 | TOO_MANY_PARTS | O formulário tem mais do que um ficheiro ou mais de 10 campos |
| 415 | MULTIPART_REQUIRED | A proposta tem de ser enviada em multipart/form-data |
| 415 | UNSUPPORTED_FILE | Formato de ficheiro não aceite numa proposta |
| 415 | UNSUPPORTED_MEDIA_TYPE | O endpoint não aceita multipart/form-data |
| 429 | RATE_LIMITED | Demasiados pedidos por minuto (vê Retry-After) |
| 429 | PROPOSAL_LIMIT_REACHED | Já enviaste 10 propostas nas últimas 24 horas |
Login por código (plugins)
Os endpoints /device/code e
/device/token, usados pelo plugin do
Figma e pela extensão do Chrome, seguem a norma do login por código de
dispositivo (RFC 8628), com códigos em minúsculas:
| Estado | Código | Significado |
|---|---|---|
| 400 | authorization_pending | O utilizador ainda não confirmou o código: pergunta de novo daqui a interval segundos |
| 400 | slow_down | Estás a perguntar depressa demais: aumenta o intervalo |
| 400 | access_denied | O utilizador recusou a ligação |
| 400 | expired_token | O código passou do prazo (10 minutos) |
| 400 | invalid_grant | Código desconhecido ou já usado |
| 409 | token_limit | A conta já tem 20 tokens activos |