Erros e limites da API
O formato JSON de cada erro da API REST da Endless, o campo data.code para decidir o que fazer e os cabeçalhos RateLimit de 1.000 requisições por minuto.
Todo erro da API REST da Endless em https://api.endless.app retorna JSON em um único formato, e toda resposta informa quantas requisições ainda restam. O versionamento tem página própria.
O formato de um erro
{
"code": "FORBIDDEN",
"status": 403,
"message": "Your role does not have permission to do this",
"data": { "code": "permission_denied" }
}| Campo | O que é |
|---|---|
code | O status HTTP como palavra: BAD_REQUEST, UNAUTHORIZED, NOT_FOUND, … |
status | O status HTTP como número |
message | Uma frase para uma pessoa. Pode mudar de redação, então não compare com ela |
data.code | O motivo legível por máquina, em snake_case. É o campo para decidir o que fazer |
data.hint | Quando presente, o passo que resolve |
data.documentation | Quando presente, um link para a referência da API |
O schema Error no documento OpenAPI lista cada data.code, e cada operação na referência da API lista seus status.
Códigos comuns
| Status | data.code | O que fazer |
|---|---|---|
| 400 | (validação) | message diz o campo e a regra que ele violou |
| 400 | unsupported_api_version | Veja Versões da API |
| 401 | missing_token | Envie Authorization: Bearer <token> |
| 401 | invalid_token | O token não foi verificado ou expirou. Obtenha um novo |
| 402 | insufficient_credits, exceeds_spending_limit | O espaço de trabalho ou quem chama não pode pagar a chamada |
| 403 | permission_denied, forbidden | A função ou o acesso de quem chama não permite |
| 404 | not_found, organization_not_found, … | O recurso não existe, ou quem chama não pode abri-lo |
| 404 | route_not_found | Nenhuma operação corresponde ao caminho (nunca uma página HTML) |
| 404 | invalid_path_parameter | Um id no caminho não pode nomear um recurso |
| 429 | rate_limited | Espere os segundos de retry_after e tente de novo |
Limites de requisições
- Limite: 1.000 requisições a cada 60 segundos por quem chama, em uma política chamada
default. Um único contador por quem chama em todos os servidores. - Janela fixa: ela reinicia de uma vez, então controle o ritmo por
RateLimit-Remaining, não supondo um ritmo constante. - Créditos são separados: ficar sem saldo ou sem limite de gastos retorna
402, não429.
Toda resposta da API, com sucesso ou erro, traz o contador em dois formatos (navegadores também podem lê-los):
RateLimit-Policy: "default";q=1000;w=60
RateLimit: "default";r=997;t=42
RateLimit-Limit: 1000
RateLimit-Remaining: 997
RateLimit-Reset: 42r / RateLimit-Remaining são as requisições restantes; t / RateLimit-Reset são os segundos até reiniciar. Acima do limite, a API responde 429 com um cabeçalho Retry-After e os mesmos segundos no corpo:
{
"code": "TOO_MANY_REQUESTS",
"status": 429,
"message": "Too many requests.",
"data": {
"code": "rate_limited",
"hint": "Wait 42s, then retry. Every response carries RateLimit headers — read them to pace yourself before you are refused.",
"documentation": "https://endless.app/docs/api"
},
"retry_after": 42
}Fontes legíveis por máquina
- Índice da API: seus objetos
rate_limiteerrorsdescrevem esta política. - Documento OpenAPI: o schema
Errorem cada resposta de erro. - O servidor MCP tem limite próprio: 60 chamadas de ferramentas por minuto por conta.