> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Erros ## Erros da API A ElevenLabs usa códigos de status HTTP padrão para indicar o sucesso ou a falha de uma solicitação. Além disso, todas as solicitações à API retornam um objeto JSON com uma propriedade `detail` que contém informações sobre o erro. Em geral, um código de status HTTP `200` indica uma solicitação bem-sucedida. Um código `4xx` indica um problema com a solicitação, como um parâmetro inválido ou um campo obrigatório ausente. Um código de status HTTP `500` indica um problema nos servidores da ElevenLabs, o que deve ser raro. ### Propriedades do erro | Propriedade | Descrição | | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | | `type` | O tipo de erro ocorrido. Consulte a tabela abaixo para ver os valores possíveis. | | `code` | O código do erro. Esses códigos são mais específicos do que o tipo e podem ser usados para determinar a causa do erro. | | `message` | A mensagem do erro. Ela fornece mais detalhes sobre o erro. | | `status` | O status do erro. Este é um campo legado que não é mais usado; use a propriedade `code`. | | `request_id` | O ID da solicitação que causou o erro. É um identificador exclusivo da solicitação que pode ser usado para solucionar o erro. | | `param` | O parâmetro que causou o erro. No caso de um erro de validação, ele indicará qual parâmetro é inválido. | ### Exemplo de resposta de erro Esta é a resposta para uma solicitação à API que usou um ID de modelo incorreto: ```json { "detail": { "type": "validation_error", "code": "invalid_parameters", "message": "The 'keyterms' parameter is only supported with the 'scribe_v2' model. You specified 'scribe_v1'.", "status": "invalid_parameters", "request_id": "3c807fc4c3a1705f9638ecc764a91c01", "param": "keyterms" } } ``` Usando as propriedades do erro, podemos ver que se trata de um erro de validação e que o código é `invalid_parameters`. A mensagem fornece mais detalhes sobre o erro, e o `request_id` é um identificador exclusivo da solicitação que pode ser usado para solucionar o erro. A propriedade `param` indica o parâmetro que causou o erro. ### Tratamento de erros no SDK Os SDKs da ElevenLabs oferecem classes de erro tipadas que dão acesso aos detalhes do erro. ```python from elevenlabs import ElevenLabs from elevenlabs.core import ApiError elevenlabs = ElevenLabs() try: audio = elevenlabs.text_to_speech.convert( voice_id="invalid-voice-id", model_id="eleven_v4", text="Hello, world!", ) except ApiError as e: print(f"Status code: {e.status_code}") # Access the error body if e.body and "detail" in e.body: detail = e.body["detail"] print(f"Error type: {detail.get('type')}") print(f"Error code: {detail.get('code')}") print(f"Message: {detail.get('message')}") print(f"Request ID: {detail.get('request_id')}") # Handle specific error types if detail.get("type") == "rate_limit_error": print("Rate limited - implement exponential backoff") elif detail.get("type") == "authentication_error": print("Check your API key") ``` ```typescript import { ElevenLabsClient, ElevenLabsError } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); try { const audio = await elevenlabs.textToSpeech.convert("invalid-voice-id", { text: "Hello, world!", modelId: "eleven_v4", }); } catch (error) { if (error instanceof ElevenLabsError) { console.log(`Status code: ${error.statusCode}`); // Access the error body const detail = (error.body as any)?.detail; if (detail) { console.log(`Error type: ${detail.type}`); console.log(`Error code: ${detail.code}`); console.log(`Message: ${detail.message}`); console.log(`Request ID: ${detail.request_id}`); // Handle specific error types if (detail.type === "rate_limit_error") { console.log("Rate limited - implement exponential backoff"); } else if (detail.type === "authentication_error") { console.log("Check your API key"); } } } } ``` Se não conseguir resolver o erro, envie um e-mail para o Suporte em [support@elevenlabs.io](mailto:support@elevenlabs.io) com o `request_id` da resposta de erro, a mensagem de erro completa e as etapas para reproduzir o problema. #### Limite de taxa e simultaneidade Se você receber um código de status HTTP 429, isso significa que fez muitas solicitações em um curto período e excedeu o limite de taxa do endpoint da API, ou que excedeu o limite de simultaneidade do endpoint da API. O `code` do erro será `rate_limit_exceeded` ou `concurrent_limit_exceeded`, respectivamente. No caso de limite de taxa, você deve implementar backoff exponencial no código ao receber um erro 429. Isso significa adicionar um atraso antes de tentar a solicitação novamente. No caso de simultaneidade, você deve aguardar a conclusão das solicitações atuais antes de fazer novas. Consulte a seção [Simultaneidade e prioridade](/docs/pt/overview/models#concurrency-and-priority) para mais informações. ### Tipos de erro Um erro vem com uma propriedade `type` que indica o tipo de erro ocorrido. Consulte a tabela abaixo para ver os valores possíveis. | Tipo | Descrição | Código de status HTTP | | ---------------------- | ------------------------------------------------------------------------- | --------------------- | | `validation_error` | A solicitação contém valores de parâmetros inválidos. | 400 | | `invalid_request` | A estrutura da solicitação está malformada ou faltam campos obrigatórios. | 400 | | `authentication_error` | A autenticação falhou: chave ou token da API inválido ou ausente. | 401 | | `payment_required` | O usuário não tem créditos suficientes ou é necessário efetuar pagamento. | 402 | | `authorization_error` | O usuário autenticado não tem as permissões necessárias para esta ação. | 403 | | `not_found` | O recurso solicitado não foi encontrado. | 404 | | `conflict` | A solicitação entra em conflito com o estado atual do recurso. | 409 | | `rate_limit_error` | Muitas solicitações: tente novamente mais tarde. | 429 | | `internal_error` | Ocorreu um erro inesperado no servidor. | 500 | | `service_unavailable` | O serviço está temporariamente indisponível; isso deve ocorrer raramente. | 503 | ### Códigos de erro
Código Tipo Descrição
`voice_not_found` `not_found` O ID de voz especificado não existe. Verifique o ID de voz e tente novamente.
`sample_not_found` `not_found` A amostra de voz especificada não foi encontrada.
`voice_collection_not_found` `not_found` A coleção de vozes especificada não existe.
`user_not_found` `not_found` O usuário especificado não foi encontrado.
`auth_account_not_found` `not_found` A conta de autenticação não foi encontrada.
`workspace_not_found` `not_found` O espaço de trabalho especificado não existe.
`project_not_found` `not_found` O projeto especificado não foi encontrado.
`history_item_not_found` `not_found` O item de histórico especificado não existe.
`collection_not_found` `not_found` A coleção especificada não foi encontrada.
`document_not_found` `not_found` O documento especificado não existe.
`file_not_found` `not_found` O arquivo especificado não foi encontrado.
`conversation_not_found` `not_found` A conversa especificada não existe.
`agent_not_found` `not_found` O agente especificado não foi encontrado.
`dubbing_not_found` `not_found` O projeto de dublagem especificado não existe.
`song_not_found` `not_found` A música especificada não foi encontrada.
`read_not_found` `not_found` A leitura especificada não foi encontrada.
`pronunciation_dictionary_not_found` `not_found` O dicionário de pronúncia especificado não existe.
`knowledge_base_not_found` `not_found` A base de conhecimento especificada não foi encontrada.
`phone_number_not_found` `not_found` O número de telefone especificado não existe.
`tool_not_found` `not_found` A ferramenta especificada não foi encontrada.
`snapshot_not_found` `not_found` O snapshot especificado não existe.
`task_not_found` `not_found` A tarefa especificada não foi encontrada.
`model_not_found` `not_found` O modelo especificado não existe.
`transcript_not_found` `not_found` A transcrição especificada não foi encontrada.
`keywords_list_not_found` `not_found` A lista de palavras-chave especificada não foi encontrada.
`category_not_found` `not_found` A categoria especificada não foi encontrada.
`text_too_long` `validation_error` O texto fornecido excede o tamanho máximo permitido.
`text_too_short` `validation_error` O texto fornecido é menor que o tamanho mínimo exigido.
`invalid_text` `validation_error` O texto fornecido contém caracteres ou formatação inválidos.
`empty_text` `validation_error` O campo de texto não pode estar vazio.
`invalid_parameters` `validation_error` Um ou mais parâmetros da solicitação são inválidos. Verifique a propriedade `param` para identificar o parâmetro inválido.
`missing_required_field` `validation_error` Está faltando um campo obrigatório na solicitação. Verifique a propriedade `param` para identificar o campo ausente.
`invalid_voice_settings` `validation_error` As configurações de voz contêm valores inválidos. Verifique a propriedade `param` para identificar as configurações de voz inválidas.
`invalid_voice_id` `validation_error` O formato do ID de voz é inválido.
`unsupported_model` `validation_error` O modelo especificado não é compatível com esta operação.
`invalid_audio` `validation_error` O áudio fornecido é inválido ou está corrompido.
`invalid_audio_format` `validation_error` O formato de áudio especificado não é compatível.
`invalid_output_format` `validation_error` O formato de saída solicitado não é compatível.
`audio_too_long` `validation_error` O áudio excede a duração máxima permitida.
`audio_too_short` `validation_error` O áudio é mais curto que a duração mínima exigida.
`invalid_file_type` `validation_error` O tipo de arquivo não é compatível.
`invalid_page_size` `validation_error` O parâmetro de tamanho da página está fora do intervalo permitido.
`invalid_cursor` `validation_error` O cursor de paginação é inválido ou expirou.
`bad_request` `invalid_request` O servidor não conseguiu entender a solicitação.
`malformed_json` `invalid_request` O corpo da solicitação contém JSON inválido.
`invalid_content_type` `invalid_request` O cabeçalho Content-Type está ausente ou é inválido.
`request_too_large` `invalid_request` O corpo da solicitação excede o tamanho máximo permitido.
`invalid_api_key` `authentication_error` A chave de API fornecida é inválida.
`missing_api_key` `authentication_error` Nenhuma chave de API foi fornecida na solicitação.
`invalid_authorization_header` `authentication_error` O formato do cabeçalho Authorization é inválido.
`unauthorized` `authentication_error` É necessário autenticar-se para acessar este recurso.
`sign_in_required` `authentication_error` Você precisa estar conectado para realizar esta ação.
`forbidden` `authorization_error` O acesso a este recurso é proibido.
`insufficient_permissions` `authorization_error` Você não tem as permissões necessárias para esta ação.
`workspace_access_denied` `authorization_error` Você não tem acesso a este espaço de trabalho.
`feature_not_available` `authorization_error` Este recurso não está disponível no seu plano atual.
`subscription_required` `authorization_error` É necessária uma assinatura paga para acessar este recurso.
`voice_access_denied` `authorization_error` Você não tem acesso a esta voz.
`model_access_denied` `authorization_error` Você não tem acesso a este modelo.
`conflict` `conflict` Ocorreu um conflito.
`resource_already_exists` `conflict` Já existe um recurso com o mesmo identificador.
`voice_already_exists` `conflict` Já existe uma voz com este nome.
`already_running` `conflict` A operação já está em execução.
`already_processing` `conflict` O recurso já está sendo processado.
`concurrent_modification` `conflict` O recurso foi modificado por outra solicitação. Tente novamente com a versão mais recente.
`slug_already_exists` `conflict` Já existe um recurso com este slug.
`rate_limit_exceeded` `rate_limit_error` Muitas solicitações. Aguarde antes de tentar novamente.
`concurrent_limit_exceeded` `rate_limit_error` O número máximo de solicitações simultâneas foi excedido. Planos de assinatura superiores têm um limite de simultaneidade maior.
`system_busy` `rate_limit_error` O sistema está ocupado no momento. Tente novamente mais tarde.
`insufficient_credits` `payment_required` Sua conta não tem créditos suficientes para esta operação.
`internal_error` `internal_error` Ocorreu um erro inesperado. Entre em contato com o suporte se ele persistir.
`service_unavailable` `service_unavailable` O serviço está temporariamente indisponível. Tente novamente mais tarde.
`maintenance` `service_unavailable` O serviço está passando por manutenção programada.