Lide com códigos de erro públicos da Rivya API, status HTTP, limites de taxa, conflitos de idempotência e decisões de nova tentativa.

A Rivya API retorna códigos de erro públicos estáveis em JSON. Trate o valor error.code como o contrato de integração.

Formato do Erro

{
  "error": {
    "code": "api_key_missing",
    "message": "A valid Bearer API key is required.",
    "requestId": "req_..."
  }
}

Mantenha requestId nos seus logs ao pedir que o suporte da Rivya investigue uma solicitação de API com falha.

Códigos de Erro Estáveis

Code	HTTP status	Meaning	Suggested action
`public_api_disabled`	503	Chamadas da API pública estão temporariamente desativadas.	Tente novamente mais tarde ou use o Studio manualmente.
`api_key_missing`	401	A solicitação não incluiu uma chave de API Bearer.	Envie `Authorization: Bearer rvya_sk_...`.
`api_key_invalid`	401	A chave não pode ser verificada.	Verifique a chave e rotacione se necessário.
`api_key_revoked`	401	A chave foi revogada em Configurações.	Crie uma nova chave.
`api_key_expired`	401	A chave não é mais válida.	Crie uma nova chave.
`api_scope_denied`	403	A chave não tem o escopo necessário.	Crie uma chave com o escopo necessário.
`rate_limited`	429	Muitas solicitações na janela atual.	Reduza o ritmo e tente novamente mais tarde.
`validation_failed`	400	O corpo, modelo, prompt ou params são inválidos.	Compare seu corpo com a referência do modelo.
`not_found`	404	A tarefa solicitada não existe ou não pertence à conta.	Verifique o ID público da tarefa e o limite da conta.
`webhook_url_rejected`	400	A URL do endpoint de webhook não é permitida.	Use uma URL pública HTTPS sem credenciais, fragmentos, localhost ou endereços de rede privada.
`chat_model_not_supported`	400	O modelo selecionado não está disponível para a Chat API.	Leia `/api/v1/models` e escolha um modelo de chat disponível.
`chat_session_conflict`	409	A sessão de chat não pode ser usada para esta solicitação.	Use uma sessão criada pela API, pertencente à mesma conta e ao mesmo modelo.
`chat_attachment_not_supported`	400	O anexo de chat não é suportado.	Faça upload de uma imagem pela Files API e envie seu `file_id`.
`idempotency_conflict`	409	A mesma chave de idempotência foi reutilizada com entrada diferente.	Use uma nova chave ou reenvie exatamente o mesmo corpo.
`insufficient_credits`	402	A conta não tem créditos suficientes.	Adicione créditos ou escolha uma solicitação de menor custo.
`internal_error`	500	A solicitação não pôde ser concluída.	Tente novamente com idempotência ou entre em contato com o suporte usando `requestId`.

Limites de Taxa

A Rivya aplica limites de taxa da Public API em nível de aplicação por chave de API. O limite padrão de produção é configurado por PUBLIC_API_RATE_LIMIT_PER_MINUTE.

Quando receber rate_limited, use backoff exponencial. Não tente novamente em um loop apertado.

Novas Tentativas Idempotentes

Envie Idempotency-Key em toda solicitação de produção POST /api/v1/generations e POST /api/v1/chat/completions.

Padrão recomendado:

gere uma chave única por solicitação lógica de geração
reutilize a mesma chave apenas ao repetir o mesmo corpo
armazene o ID público da tarefa retornado junto ao seu próprio registro de job
para a Chat API, armazene o session_id retornado quando quiser continuar a mesma conversa
não reutilize uma chave para outro modelo, prompt ou params

Se a rede falhar depois do envio, tente novamente com o mesmo corpo e a mesma Idempotency-Key. A Rivya pode retornar a resposta pública armazenada em vez de criar uma tarefa duplicada.

Decisões de Nova Tentativa

Tente novamente estes com backoff:

public_api_disabled
rate_limited
internal_error
falhas temporárias de rede

Não tente novamente estes sem alterar a entrada:

api_key_invalid
api_key_revoked
api_scope_denied
validation_failed
webhook_url_rejected
chat_model_not_supported
chat_session_conflict
chat_attachment_not_supported
idempotency_conflict
insufficient_credits

Erros e Limites da API

Formato do Erro

Códigos de Erro Estáveis

Limites de Taxa

Novas Tentativas Idempotentes

Decisões de Nova Tentativa

Páginas Relacionadas

Sumário