Erros e limites
O formato dos erros, cada código e o limite de 60 chamadas por minuto.
Formato
Todo erro responde com o status HTTP e o mesmo corpo JSON:
{
"error": {
"code": "invalid_input",
"message": "Too small: expected string to have >=1 characters",
"param": "title",
"requestId": "req_8f14e45fceea167a5a36dedd4bea2543"
}
}| Campo | O que é |
|---|---|
code | Um código estável, em inglês, feito para o seu código comparar. |
message | Uma explicação para pessoas. Pode mudar; não compare. |
param | O campo da entrada que causou o erro, quando há um. |
requestId | O id da requisição. Vai também no cabeçalho x-request-id de toda resposta, de sucesso ou de erro; mande-o ao suporte. |
Códigos
| Status | code | Quando |
|---|---|---|
400 | invalid_input | O corpo, a query ou o cursor não é válido: JSON malformado, campo faltando ou fora do limite. param diz qual. |
400 | invalid_url, invalid_image, fetch_failed | A imagem enviada por URL não é https pública, não respondeu, ou não é JPG, PNG ou WebP. |
401 | invalid_token | Token ausente, desconhecido, expirado ou revogado. |
402 | insufficient_credits | A geração pelo modelo do Postline precisa de mais créditos do que o workspace tem. |
403 | insufficient_scope | O token não tem a permissão que o endpoint pede. |
403 | not_allowed | O papel de quem criou o token não permite a ação (por exemplo, aprovar). |
403 | project_not_allowed | O projectId não é o projeto do token. |
404 | not_found | O recurso não existe nos projetos que o token alcança. |
409 | conflict | Você salvou sobre uma revisão antiga: leia de novo e mande a revision atual. |
409 | locked, invalid_state, not_deletable | O artigo ou o post não está no estado para isso: em revisão, sendo escrito, não aprovado, ou já publicado. |
409 | slug_taken | Outro artigo do projeto já usa esse slug. |
413 | too_large, storage_full | A imagem passa de 20 MB, ou o armazenamento do plano está cheio. |
429 | rate_limited | Mais de 60 chamadas no minuto com o mesmo token. |
500 | internal_error | Uma falha nossa. Tente de novo; se repetir, mande o requestId. |
503 | unavailable | Armazenamento ou geração de imagens indisponível. Tente de novo mais tarde. |
Cada endpoint lista os seus na Referência da API.
Limite de chamadas
Cada token de API faz até 60 chamadas por minuto. A janela começa na primeira chamada e dura 60 segundos; a 61ª chamada dentro dela recebe 429 rate_limited. Chamadas recusadas por token (401) não entram na conta.
A resposta não traz cabeçalhos de limite (Retry-After, X-RateLimit-*). Ao receber 429, espere a janela acabar (no máximo um minuto) e tente de novo, de preferência com recuo exponencial:
async function withRetry(call: () => Promise<Response>, tries = 4) {
for (let attempt = 0; ; attempt++) {
const response = await call()
if (response.status !== 429 || attempt === tries - 1) return response
await new Promise((r) => setTimeout(r, 2 ** attempt * 15_000))
}
}O servidor MCP tem o mesmo limite, por assistente conectado. A leitura do site (com o token de leitura) não tem limite por token.
Uso
Em Organização › Chaves de API, o painel Uso nos últimos 7 dias mostra as chamadas e os erros da API.