Limites e erros

Limites

Os limites valem por token de aplicativo e funcionam como um balde de fichas: cada requisição gasta uma ficha, e o balde se reabastece com o tempo.

Limite	Taxa	Rajada
Por instalação	10 requisições por segundo	30
Por aplicativo (soma de todas as instalações)	50 requisições por segundo	100

Estes são os valores padrão atuais e podem ser ajustados pela owiew. Além deles:

Recurso	Limite
Corpo de cada entrega de webhook	256 KiB
Tempo de resposta do seu receptor	10 segundos
Tentativas de uma entrega	10, em até 24 horas
Validade do token de app	2 minutos
Projetos por instalação	até 50
Tamanho do cursor	512 caracteres
Itens por página	1 a 200 (padrão 50)

O endpoint de token tem um freio contra tentativa em massa, por client_id e IP. Quando ele dispara, a resposta é 429 com error igual a temporarily_unavailable e o cabeçalho Retry-After.

Cabeçalhos de limite

Toda resposta de dado da /apps/v1 leva:

Cabeçalho	Significado
`RateLimit-Limit`	A rajada do balde da instalação
`RateLimit-Remaining`	Fichas que sobram
`RateLimit-Reset`	Segundos até o balde encher por completo
`Retry-After`	Só no `429`: segundos até tentar de novo

Ao receber 429, espere o tempo de Retry-After e tente de novo com espera crescente. Não reenvie em laço fechado.

Formato de erro

Os erros da /apps/v1 seguem a RFC 9457 (application/problem+json):

{
  "type": "https://owiew.com/problemas/escopo-insuficiente",
  "title": "Escopo insuficiente para esta operação",
  "status": 403,
  "codigo": "escopo-insuficiente",
  "detail": "Esta rota exige o escopo `metricas:read`.",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Use codigo para decidir o que fazer, não o texto de detail. Guarde o trace_id ao abrir um chamado: ele liga a sua requisição ao registro da owiew. O detail nunca contém segredo nem dado pessoal.

Códigos

Status	`codigo`	Quando	O que fazer
400	`pedido-invalido`	Cursor ou `limite` fora da faixa, texto com caractere de controle	Corrija o parâmetro
401	`nao-autenticado`	Token ausente, malformado, expirado, de outra audiência, instalação revogada ou aplicativo suspenso	Peça um token novo. Se persistir, a instalação pode ter sido desinstalada
403	`acesso-negado`	Trava de IP ligada e origem fora da lista	Chame a partir de um IP autorizado
403	`escopo-insuficiente`	O token não tem o escopo da rota	Peça o escopo numa nova versão do aplicativo
404	`nao-encontrado`	Rota ou recurso inexistente neste projeto	Confira o caminho
405	`metodo-nao-permitido`	Método diferente de `GET`	Use `GET`
429	`limite-de-taxa`	Limite da instalação ou do aplicativo excedido	Espere `Retry-After`
500	`erro-interno`	Defeito da owiew	Tente de novo e informe o `trace_id` se persistir
503	`indisponivel`	Dependência fora, ou a lista de revogações ficou desatualizada por mais de 2 minutos	Tente de novo depois de `Retry-After` (5 segundos)

Entrada hostil (unicode estranho, byte nulo, cursor adulterado) nunca vira 500: vira 400.

Por que o `401` não diz o motivo

Todas as falhas de credencial devolvem exatamente a mesma resposta, com WWW-Authenticate: Bearer error="invalid_token". Isso impede que um atacante descubra se um identificador existe. Para diagnosticar o seu próprio token, decodifique-o e confira as regras da página modelo de acesso.

Falha fechada

Se a owiew não consegue atualizar a lista de instalações revogadas por mais de 2 minutos, a /apps/v1 responde 503 em vez de aceitar tokens sem conferir revogação. Trate 503 como temporário.

Erros de entrega de webhook

Quando uma entrega falha, a owiew registra um código sanitizado, sem dados do seu servidor:

Código	Significado
`http-<status>`	Seu servidor respondeu com um status que não é `2xx`
`redirecionamento`	Seu servidor respondeu `3xx`
`timeout`	Não respondeu em 10 segundos
`rede`, `dns`, `tls`	Falha de conexão, de resolução de nome ou de certificado
`destino-proibido`	O endereço resolveu para uma rede interna ou reservada
`destino-fora-da-lista`	Trava de IP ligada e o IP do destino está fora da lista
`corpo-grande`	Corpo acima de 256 KiB
`inscricao-inativa`, `modulo-inativo`, `projeto-revogado`, `app-inativo`	A entrega foi descartada porque a inscrição, o módulo, o projeto ou o aplicativo deixou de estar ativo