Erros
Formato de erro e códigos de status comuns do Open API.
Erros
Erros API abertos usam corpos de resposta JSON quando a solicitação atinge a camada API. Falhas de rede, falhas de CDN e interrupções de resposta binária podem não ter esse formato exato, portanto, seu cliente deve lidar com erros API estruturados e erros de transporte.
Cada endpoint usa o mesmo contexto de autenticação de portador:
Authorization: Bearer FISHAUDIO_API_KEY{
"code": "invalid_request",
"message": "The request payload is invalid.",
"requestId": "req_xxx"
}Códigos de status
| Estado | Significado | Ação típica |
|---|---|---|
400 | Corpo de solicitação, parâmetro de caminho, parâmetro de consulta ou URL de mídia inválidos | Corrija a solicitação antes de tentar novamente |
401 | Chave API ausente, malformada, revogada ou desativada | Interrompa novas tentativas e atualize credenciais |
402 | Créditos insuficientes, cota API ou alocação de provedor | Interrompa o lote e mostre o estado de cobrança |
404 | O ID do recurso é desconhecido para a conta autenticada | Atualizar registros locais |
409 | O recurso está em um estado que entra em conflito com a operação | Aguarde ou remova dependências |
422 | A mídia foi aceita, mas não pode ser processada | Solicite diferentes mídias de entrada |
429 | Limite de taxa excedido | Tentar novamente com espera exponencial |
500 | Erro no servidor | Tente novamente algumas vezes e registre requestId |
Registro de solicitação
Registre o endpoint, o método HTTP, o status, code, requestId e seu próprio ID de trabalho interno. Não registre chaves API do portador, texto completo do usuário ou URLs de mídia privada, a menos que sua política de privacidade e fluxo de trabalho de suporte permitam explicitamente.
Para endpoints assíncronos, inclua o ID da tarefa API e o ID do banco de dados interno nos logs. Isso torna possível reconciliar novas tentativas sem criar trabalho duplicado.
Faturamento e créditos
Nem todo erro tem o mesmo significado de faturamento. As falhas de validação normalmente acontecem antes do início do trabalho de mídia. Falhas de processamento podem ocorrer após a aceitação de uma tarefa. Para perguntas de faturamento voltadas ao usuário, compare o status da tarefa com uma leitura recente do Perfil em vez de inferir o custo apenas do status HTTP.
Política de Nova Tentativa
Tente novamente 429 e algumas respostas 500 com espera. Não tente novamente 400, 401 ou 402 cegamente; aqueles exigem alterações de solicitação, credencial ou faturamento. Para criar endpoints, persista o ID retornado antes de tentar novamente qualquer operação de acompanhamento.