> ## Documentation Index > Fetch the complete documentation index at: https://docs.flexinference.com/llms.txt > Use this file to discover all available pages before exploring further. # Erros > Os envelopes de erro por superfície, códigos FlexInference e como os erros do provedor são normalizados. Os erros usam o envelope do endpoint que você chama. `/v1/responses` e `/v1/chat/completions` retornam erros no formato OpenAI. `/v1/messages` retorna erros no formato Anthropic. `/v1/interactions` retorna erros no formato Google. Os erros do FlexInference e os erros dos provedores upstream seguem a mesma regra, então cada endpoint tem um único formato de erro. Está vendo erros 5xx ou timeouts? Verifique [status.flexinference.com](https://status.flexinference.com) primeiro. Ele mostra o tempo de atividade em tempo real para a API, site, documentação e servidor MCP, além de qualquer incidente aberto. Em `/v1/responses` e `/v1/chat/completions`, os erros usam o envelope OpenAI: ```json theme={null} { "error": { "message": "The API key on this request was rejected - either it does not match FlexInference's key format (`flex_live_` followed by 24 hex characters and a 6-hex checksum), or it is well-formed but does not match any key on record. Copy the exact, current key from the FlexInference dashboard under Settings -> API keys, then send it as `Authorization: Bearer `.", "type": "authentication_error", "code": "invalid_api_key", "param": null, "doc_url": "https://docs.flexinference.com/errors#invalid_api_key" } } ``` O mesmo erro em `/v1/messages` usa o formato da Anthropic. Em `/v1/interactions`, ele usa o formato do Google: ```json theme={null} { "type": "error", "error": { "type": "authentication_error", "message": "..." } } ``` ```json theme={null} { "error": { "code": 401, "message": "...", "status": "UNAUTHENTICATED" } } ``` O status HTTP e a mensagem permanecem os mesmos em todas as superfícies; apenas o invólucro muda. O envelope OpenAI contém todos os detalhes. `type` usa categorias OpenAI (`invalid_request_error`, `authentication_error`, `rate_limit_error`), além de `flexinference_error` para falhas internas e `billing_error` quando o status de faturamento pausa as requisições faturáveis. `code` é o motivo legível por máquina. `param` nomeia o campo problemático, quando aplicável. `doc_url` linka para a linha desse código abaixo, ou é `null` quando desconhecido. O formato Anthropic contém um `type` Anthropic mapeado do status mais a mensagem. O formato Google contém o `code` numérico, a mensagem e um `status` canônico. `code` e `doc_url` específicos do FlexInference aparecem apenas no envelope OpenAI. ## Códigos FlexInference Esses códigos vêm do FlexInference. Faça um branch em `error.code`; `error.message` é escrito para desenvolvedores e inclui a correção, quando existe. Vários erros envolvem `start_within`. Para valores de duração em modelos compatíveis com flex, o FlexInference tenta primeiro o tier flex mais barato. Se o flex não puder iniciar dentro desse período, o FlexInference envia a mesma requisição para o tier padrão. O padrão é o caminho de backup, não a primeira tentativa. | Status | Code | Meaning | | ------ | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401` | `missing_api_key` | Nenhum cabeçalho `Authorization`, ou o valor não é `Bearer `. Envie `Authorization: Bearer `. | | `401` | `invalid_api_key` | A chave não corresponde ao formato do FlexInference (`flex_live_` + 24 caracteres hexadecimais + um checksum de 6 caracteres hexadecimais), ou corresponde ao formato, mas é desconhecida porque foi revogada, regenerada ou digitada incorretamente. Copie a chave atual do painel. | | `429` | `rate_limit_exceeded` | A requisição atingiu um destes limites: tentativas de autenticação falhas do seu IP de cliente, requisições de uma chave ou IP de cliente, requisições da sua organização ou leases de concorrência flex faturáveis. O limitador de concorrência flex faturável padrão é de 20 requisições em andamento. Aguarde os segundos em `Retry-After`, geralmente 60s para o limitador de inundação de autenticação e 5s para os outros limitadores de requisição. | | `402` | `payment_required` | Esta organização tem um saldo em atraso ou nenhum método de pagamento registrado, então as requisições flex faturáveis estão pausadas. O roteamento gratuito (`default`, `priority`, `auto`) e todas as requisições do tier Anthropic continuam funcionando. Adicione ou atualize um cartão na página [Faturamento](/pt/billing) do painel e tente novamente. Este é o único código com `type: billing_error`. | | `413` | `request_too_large` | O corpo da requisição excede o limite de 1.000.000 bytes do FlexInference, verificado tanto contra o `Content-Length` declarado quanto os bytes realmente transmitidos. Arquivos base64 inline grandes são a causa usual. Diminua o payload ou aponte para uma URL hospedada. | | `400` | `no_byok_key` | Nenhuma chave OpenAI está configurada para sua organização. Adicione uma no painel em Configurações -> Chaves de API. As chaves BYOK são armazenadas criptografadas; se uma chave armazenada existir, mas não puder ser descriptografada, a requisição falha como `500 internal_error`, não com este código. Cada rota que você nomeia em uma cadeia `provider` precisa de sua chave: uma chave ausente é um erro de configuração, não uma falha transitória, então é rejeitada antes de qualquer chamada upstream e nunca passa para a próxima rota. | | `400` | `no_gemini_key` | O mesmo que `no_byok_key`, para um modelo `gemini-*`: nenhuma chave Gemini está configurada para sua organização. Adicione uma no painel. | | `400` | `no_anthropic_key` | O mesmo que `no_byok_key`, para um modelo `claude-*`: nenhuma chave Anthropic está configurada para sua organização. Adicione uma no painel. | | `400` | `no_bedrock_key` | O mesmo que `no_byok_key`, para uma rota `bedrock` na cadeia `provider`: nenhuma chave Bedrock está configurada para sua organização. O Bedrock serve modelos `claude-*` através do Amazon Bedrock usando sua própria chave; adicione uma no painel em Configurações -> Chaves de API. Uma entrada `bedrock` em qualquer lugar da cadeia requer a chave, então uma chave ausente é rejeitada antes de qualquer chamada upstream. | | `400` | `no_vertex_key` | O mesmo que `no_byok_key`, para uma rota `vertex` na cadeia `provider`: nenhuma chave Vertex está configurada para sua organização. O Vertex serve modelos `gemini-*` através do Google Vertex AI usando sua própria chave expressa (prefixo `AQ.`); adicione uma no painel em Configurações -> Chaves de API. Uma entrada `vertex` em qualquer lugar da cadeia requer a chave, então uma chave ausente é rejeitada antes de qualquer chamada upstream. | | `400` | `missing_model` | O campo `model` está ausente, vazio ou não é uma string. Adicione uma string não vazia, por exemplo `"model": "gpt-5.5"`. | | `400` | `missing_start_within` | O campo `start_within` obrigatório está ausente e nenhum padrão é aplicado. `start_within` define quanto tempo você está disposto a esperar para que a requisição comece. Use `default`, `priority`, `auto` ou uma duração como `HHh-MMm-SSs`, por exemplo `00h-00m-30s` para esperar até trinta segundos. | | `400` | `invalid_start_within` | `start_within` não é uma string, não corresponde a uma das quatro formas aceitas, ou resolve fora da janela permitida de 5 a 600 segundos (10 minutos) para uma duração. Corresponda ao formato exato e mantenha as durações entre 5s e 600s. Por exemplo, use `"start_within": "00h-00m-30s"` para uma janela de trinta segundos, ou `"start_within": "default"` para pular a corrida flex. | | `400` | `auto_unsupported_for_gemini` | `start_within: "auto"` foi usado em um modelo Gemini. Os tiers do Gemini são apenas `flex`, `standard` e `priority`; não há `auto` para resolver. Use `default`, `priority` ou uma duração em vez disso. | | `400` | `flex_unsupported_for_anthropic` | Uma duração `start_within` (corrida flex) foi enviada para um modelo `claude-*`, mas a Anthropic não tem um tier flex para competir. O FlexInference não serve mais silenciosamente o padrão para uma corrida flex inaplicável. Use um tier `start_within` (`default`, `priority`, `auto`) ou omita-o. | | `400` | `flex_model_not_capable` | Uma duração `start_within` foi enviada para um modelo OpenAI ou Gemini que não está na lista de permissão flex. Use um tier `start_within` ou escolha um modelo compatível com flex. | | `400` | `service_tier_not_allowed` | A requisição incluiu `service_tier`. O FlexInference deriva o tier de `start_within`; aceitar `service_tier` fornecido pelo chamador exigiria sobrescrevê-lo, então o roteador rejeita o campo. Remova `service_tier` e expresse a mesma intenção através de `start_within`. Aplica-se também em `/v1/interactions` e `/v1/messages`. | | `400` | `unsupported_parameter` | Um parâmetro nativo do provedor foi enviado para um provedor diferente, ou um campo canônico de Responses não tem mapeamento para o provedor de destino. Parâmetros nativos de Chat passam em modelos OpenAI, mas falham em modelos Gemini ou Claude. Parâmetros nativos da Anthropic passam em modelos Claude, mas falham em modelos OpenAI ou Gemini, exceto blocos de conteúdo `document` e `file` com fontes base64, que são traduzidos para todos os provedores. `cache_control`, citações e outros parâmetros nativos do provedor ainda falham entre provedores. Remova o campo nomeado ou escolha um modelo cujo provedor o possua; `error.param` nomeia exatamente qual. Veja [SDKs](/pt/sdks). | | `400` | `unsupported_generation_config` | Em `/v1/interactions`, um campo `generation_config.*` não mapeado foi definido ao direcionar um modelo não-Gemini. Chaves extras nativas do Gemini passam em modelos Gemini. Remova o campo nomeado ou direcione um modelo Gemini. | | `400` | `unsupported_tool` | O array `tools` contém uma ferramenta embutida que faz o modelo emitir saída não textual, atualmente `image_generation`. O FlexInference serve apenas saída de texto, em todos os endpoints. Remova essa entrada de ferramenta; ferramentas de função e `web_search` permanecem suportadas. | | `400` | `unsupported_value` | Chat Completions `n` foi definido para algo diferente de `1`. A API Responses subjacente sempre produz uma única geração, então `n` deve ser `1` ou omitido. Por exemplo, envie `"n": 1` ou omita `n`. | | `400` | `invalid_json` | O corpo não é um JSON sintaticamente válido (`JSON.parse` falhou). Corrija a sintaxe; uma vírgula final ou uma chave sem aspas é uma causa comum. | | `400` | `invalid_body` | O corpo foi analisado como JSON, mas o valor de nível superior não é um objeto JSON. Arrays, strings, números, booleanos e nulos são inválidos. Envolva seus campos em um único objeto `{...}`. | | `400` | `invalid_stream` | O campo `stream` deve ser um booleano JSON. O FlexInference não converterá um valor não booleano, incluindo a string `"true"`, porque isso poderia escolher o modo de resposta errado. Envie `stream` como um booleano real, por exemplo `"stream": true`, ou omita-o para uma resposta não transmitida. | | `400` | `invalid_retry` | O valor de `retry` é inválido. `retry` é um objeto `{ count, backoff?, jitter? }` onde `count` é um inteiro de 1 a 5 (quantas vezes o FlexInference tenta novamente o tier upstream em um 429 ou 5xx transitório), `backoff` é `"exponential"` ou `"linear"`, e `jitter` é um booleano. Este código cobre um `count` ausente ou fora do intervalo, um valor `backoff` inválido, um `jitter` não booleano e qualquer subchave desconhecida. Corrija ou remova o campo, por exemplo `"retry": {"count": 2}`. A tentativa de repetição (retry) sempre atinge novamente o tier estabelecido antes que a resposta seja confirmada; nunca tenta novamente após o primeiro byte, uma falha de autenticação ou um 4xx do cliente. | | `400` | `invalid_provider_chain` | O array `provider` opcional está malformado: não é um array, está vazio, contém um nome de rota desconhecido, um duplicado ou mais de três entradas. Cada entrada deve ser uma de `google`, `openai`, `anthropic`, `vertex` ou `bedrock`; o elemento 0 é a rota primária e o restante é a cadeia de fallback ordenada do mesmo modelo. Omita `provider` para usar a rota nativa do modelo, ou corrija o array, por exemplo `["google", "vertex"]`. Um código cobre todas as razões de cadeia malformada, como `invalid_retry`; `error.message` nomeia a falha específica. | | `400` | `provider_model_mismatch` | Uma rota na cadeia `provider` não pode servir o modelo solicitado. Cada rota serve uma família de modelos: `openai` serve modelos GPT e da série o, `google` e `vertex` servem Gemini, e `anthropic` e `bedrock` servem Claude. Remova a rota que não corresponde a este modelo, ou envie a requisição para um modelo que essa rota possa servir, por exemplo `["anthropic"]` para um modelo `claude-*`. | | `400` | `flex_unsupported_on_cloud` | Uma duração `start_within` (uma corrida flex) foi enviada com uma rota de nuvem (`vertex` ou `bedrock`) como elemento 0, mas as rotas de nuvem não têm um tier flex para competir. O FlexInference não serve silenciosamente o tier padrão para uma corrida flex inaplicável. Use um tier `start_within` (`default`, `priority` ou `auto`) para executar a rota de nuvem como uma chamada padrão simples, ou coloque uma rota direta compatível com flex (`openai` ou `google`) primeiro em `provider`. | | `400` | `bedrock_model_unavailable` | Uma rota `bedrock` não tem um ID de modelo Amazon Bedrock para este slug, então a requisição é rejeitada antes de qualquer chamada upstream. Hoje isso significa `claude-opus-4-1` (removido da rota `bedrock` porque a AWS o publica apenas nos EUA; envie-o para `anthropic` em vez disso) ou texto `claude-*` arbitrário não mapeado. O Bedrock serve todos os modelos Claude mapeados através de seu perfil de inferência `global.`, então um modelo servido é acessível de qualquer região; o geo derivado da região (`us-*` -> `us.`, `eu-*` -> `eu.`, todo o resto -> `global.`) é apenas um fallback dormente para um futuro modelo que não publica nenhum perfil `global.`. Isso é permanente para esse slug, não transitório. Cada rota nomeada em `provider` deve ser capaz de servir a requisição, então nomear `bedrock` falha na requisição mesmo quando outra rota na cadeia poderia servir este modelo. Remova `bedrock` de `provider`, ou envie o modelo para uma rota que o sirva. | | `403` | `bedrock_model_access_denied` | O Amazon Bedrock recusou o modelo para a conta AWS por trás da chave Bedrock da sua organização, e o FlexInference repassa a própria explicação do Bedrock (`... não está disponível para esta conta`). Sua chave Bedrock é válida e está funcionando: trata-se de uma concessão de acesso por modelo ausente na conta AWS, não um problema de chave, então substituir a chave não resolverá. Para a maioria dos modelos Claude, conceda o modelo no console do Amazon Bedrock em Acesso ao modelo. Os quatro modelos mais recentes (`claude-sonnet-5`, `claude-fable-5`, `claude-opus-4-8`, `claude-opus-4-7`) adicionalmente precisam de uma configuração de conta única que a concessão do console não cobre - um opt-in de retenção de dados `provider_data_share` e um acordo de modelo, executado com credenciais de administrador da AWS; veja [a configuração dos modelos mais recentes](/pt/models). Caso contrário, envie o modelo para a rota `anthropic` em vez disso, ou escolha um modelo que a conta já possua. Esta é uma lacuna de configuração permanente, por isso é um `403` e não um `502` que pode ser retentado. | | `404` | `unknown_url` | Caminho errado. Use `/v1/responses`, `/v1/chat/completions`, `/v1/interactions` ou `/v1/messages`. | | `405` | `method_not_allowed` | O caminho existe, mas os endpoints do FlexInference aceitam apenas `POST`. Envie um `POST` com um corpo JSON. | | `499` | `client_closed_request` | O cliente desconectou antes que o FlexInference terminasse de responder, geralmente devido a uma aba fechada, fetch cancelado ou timeout do lado do cliente. Isso não é contado como uma falha de serviço. Se você não pretendia cancelar, aumente o timeout do seu cliente e deixe a requisição terminar. Uma requisição flex pode legitimamente levar até 10 minutos. | | `500` | `internal_error` | O FlexInference falhou fora da validação de entrada. Tente novamente uma vez; se persistir, entre em contato com o suporte com o timestamp aproximado e sua organização. | | `500` | `server_misconfigured` | Uma ligação ou segredo necessário está ausente ou malformado, então o FlexInference não pode autenticar chamadores ou descriptografar chaves BYOK. Esta é uma falha de implantação do lado do servidor distinta de `internal_error`, não um problema com sua requisição. Tente novamente em breve e entre em contato com o suporte se persistir. | | `502` | `upstream_stream_failed` | O provedor upstream confirmou uma resposta, então seu stream terminou sem um evento de conclusão ou falhou no meio do stream sem um erro do provedor para repassar. Esta é uma falha transitória de upstream ou de rede entre o FlexInference e o provedor, não sua requisição. Tente novamente uma vez. Se persistir para um modelo, o provedor ou o modelo pode estar degradado; tente outro modelo, ou defina uma janela `start_within` mais curta para que uma tentativa lenta seja escalada para o seu tier padrão mais cedo. Distinto de um `5xx` upstream que o próprio provedor retornou, que é remodelado para sua superfície com a mensagem do provedor. | | `502` | `upstream_unavailable` | O FlexInference não conseguiu abrir uma conexão com o provedor upstream antes que qualquer resposta fosse confirmada (a conexão foi recusada, ou DNS, TLS ou a rede falharam). Esta é uma falha de upstream ou de rede, não sua requisição. Tente novamente uma vez; se continuar falhando para um modelo, o provedor pode estar inativo, então tente outro modelo. Distinto de `upstream_stream_failed`, onde uma resposta já havia começado. | | `502` | `upstream_auth_failed` | O provedor upstream rejeitou a chave API que sua organização anexou para ele (HTTP 401 ou 403, antes que qualquer resposta fosse confirmada). Esta não é a sua chave FlexInference falhando; a credencial do provedor armazenada está sem acesso, foi revogada, expirou ou é inválida de outra forma. Peça a um administrador da organização para atualizar a chave do provedor anexada no painel em Configurações -> Chaves de API, e então tente novamente. | | `502` | `all_routes_failed` | Cada rota na cadeia `provider` falhou transitoriamente antes que qualquer resposta fosse confirmada (cada upstream tentado retornou um `429`, um `5xx`, um erro de conexão ou um timeout), então não havia mais nenhuma rota para a qual fazer fallback. Esta é uma condição de upstream ou de rede, não sua requisição, então é relatado como `502` mesmo que a própria cadeia esteja esgotada. Tente novamente uma vez; pequenos problemas de upstream geralmente se resolvem. Se persistir, tente um modelo diferente ou reduza a cadeia para as rotas que estão atualmente saudáveis. | | `503` | `usage_persistence_unavailable` | O FlexInference não conseguiu registrar duravelmente o uso para uma requisição faturável. Tente novamente assim que a persistência de uso for recuperada. | | `504` | `upstream_timeout` | O provedor upstream não começou a responder antes do timeout upstream do FlexInference, então a requisição foi abortada entre o FlexInference e o provedor. Isso é quase sempre uma lentidão ou interrupção transitória do provedor, não sua requisição, e é relatado como `504` em vez de um erro interno. Tente novamente uma vez; se continuar com timeout para um modelo, o provedor pode estar degradado, então tente outro modelo, ou para uma duração `start_within` defina um prazo mais curto como `00h-00m-30s`. | O array `provider` fixa sua rota. `google`, `openai` e `anthropic` são rotas diretas; `vertex` e `bedrock` são rotas de nuvem que servem `gemini-*` e `claude-*` no Google Vertex AI e Amazon Bedrock, respectivamente. Uma rota de nuvem cuja chave não está configurada retorna [`no_vertex_key`](/pt/errors#no_vertex_key) ou [`no_bedrock_key`](/pt/errors#no_bedrock_key), o mesmo padrão de chave ausente que [`no_gemini_key`](/pt/errors#no_gemini_key) e [`no_anthropic_key`](/pt/errors#no_anthropic_key) acima. `upstream_auth_failed` cobre qualquer credencial de provedor anexada que o upstream rejeite, incluindo rotas de nuvem. Veja [roteamento de provedor](/pt/models). ## Cabeçalhos de resultado Flex Respostas `200` bem-sucedidas incluem cabeçalhos de resultado Flex em todos os endpoints, tanto para chamadas de streaming quanto para chamadas não-streaming. As respostas de erro usam o corpo do erro em vez disso. | Header | Meaning | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `x-flexinference-flex-requested` | `true` quando o chamador enviou uma duração `start_within`; `false` quando o chamador enviou `default`, `priority` ou `auto`. | | `x-flexinference-flex-applied` | `true` apenas quando o tier flex serviu a resposta. | | `x-flexinference-flex-reason` | Resultado flex legível por máquina. Veja os valores abaixo. | | `x-flexinference-provider-surface` | Superfície de execução do provedor. Os valores são `openai.responses`, `openai.chat`, `gemini.interactions` e `anthropic.messages`. Este nem sempre é o endpoint do chamador. Uma chamada `/v1/chat/completions` com um modelo OpenAI reporta `openai.responses`, a menos que o passthrough nativo do Chat seja necessário, caso em que reporta `openai.chat`. | Valores `x-flexinference-flex-reason` em tempo real: | Reason | Meaning | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `not_requested` | A requisição usou `default`, `priority` ou `auto`, então nenhuma corrida flex foi solicitada. | | `flex_committed` | A corrida flex foi confirmada. A resposta mostra `service_tier: "flex"` e `x-flexinference-flex-applied: true`. | | `flex_lost_race` | A requisição usou uma duração em um modelo compatível com flex, mas o flex não iniciou dentro da janela e a requisição retornou ao padrão. | Uma duração que não pode executar uma corrida flex retorna `400` (`flex_unsupported_for_anthropic` em um modelo `claude-*`, `flex_model_not_capable` em um modelo OpenAI/Gemini não compatível com flex); os motivos do cabeçalho descrevem apenas requisições que executaram flex ou não o solicitaram. ## Erros do provedor Os erros do provedor upstream usam o mesmo envelope de superfície que os erros do FlexInference. O FlexInference mantém o status e a mensagem do provedor, e então os emite no envelope para o endpoint que você chamou. Um `400` do provedor para um parâmetro inválido, `401` para uma chave de provedor inválida, ou `429` de limite de taxa na tentativa padrão retorna nesse formato. Você não recebe o corpo bruto do provedor. Por exemplo, chame `/v1/messages` e um erro de modelo OpenAI retorna no formato Anthropic. `code` e `doc_url` específicos do FlexInference aparecem apenas no envelope OpenAI; erros do provedor carregam a mensagem do provedor com o `type` ou `status` da superfície. Na superfície OpenAI, faça um branch em `error.code` para tratamento específico do FlexInference, como solicitar ao usuário que adicione uma chave BYOK em `no_byok_key`. Trate códigos desconhecidos como erros OpenAI comuns. ## Tratamento de erros no código Os SDKs OpenAI levantam exceções em respostas não-2xx e anexam o corpo analisado. ```python Python theme={null} from openai import APIStatusError try: resp = client.responses.create( model="gpt-5.5", input="hi", extra_body={"start_within": "00h-00m-30s"}, ) except APIStatusError as e: code = (e.body or {}).get("error", {}).get("code") if code == "no_byok_key": print("Add your OpenAI key in the dashboard.") else: raise ``` ```typescript Node theme={null} import OpenAI from "openai"; try { await client.responses.create({ model: "gpt-5.5", input: "hi", start_within: "00h-00m-30s", } as any); } catch (e) { if (e instanceof OpenAI.APIError && e.code === "no_byok_key") { console.log("Add your OpenAI key in the dashboard."); } else { throw e; } } ```