Erros
Todo erro desta API vem no mesmo formato, com o mesmo conjunto de campos, seja qual for o endpoint ou a causa. Vale a pena tratar o código de erro programaticamente em vez da mensagem: a mensagem é para leitura humana e pode mudar sem aviso.
O envelope de erro
Toda resposta de erro vem envelopada em {"error": {...}}, nunca junto com data. O campo details traz contexto extra específico do código — por exemplo, o tempo de espera de um 429 — e pode vir vazio.
{
"error": {
"code": "INVALID_BODY",
"message": "Corpo da requisição inválido.",
"details": {}
}
}x-request-id
Toda resposta, de sucesso ou erro, traz o header x-request-id. Cite esse valor ao abrir um chamado de suporte: ele é o jeito mais rápido de localizar a requisição exata nos logs internos, sem precisar reconstruir o horário e os parâmetros da chamada.
Códigos de erro
Agrupados por status HTTP, na ordem em que a API os devolve com mais frequência dentro do grupo.
400
| Código | Quando acontece | Como resolver |
|---|---|---|
| INVALID_JSON | O corpo da requisição não é um JSON válido. | Envie JSON bem formado e o header content-type: application/json. |
| INVALID_PIN | O PIN enviado para registrar o número não confere com a verificação em duas etapas dele (erro #133005 da Meta). | Confira o PIN e tente de novo; details.attempts_remaining diz quantas tentativas restam antes de o Hub indicar a recuperação. |
| PIN_REQUIRED_RECOVERY | Três PINs recusados em uma hora: a verificação em duas etapas do número já está ativa com um PIN que não é o informado. | Redefina o PIN no WhatsApp Manager (Configurações da conta → Verificação em duas etapas) e registre de novo, ou refaça a conexão pelo link. |
| INVALID_PROFILE | Os dados de perfil do número não passaram na validação da Meta. | Confira tamanho e formato de cada campo do perfil antes de reenviar. |
| INVALID_TEMPLATE_NAME | O nome do template não segue o formato exigido pela Meta. | Use apenas letras minúsculas, números e underscore, sem espaços. |
| INVALID_TEMPLATE_ID | O hsm_id enviado na exclusão de template não tem forma de id da Meta. | Use o hsm_id que veio na listagem de templates, só dígitos. Ele é o que limita a exclusão a um idioma: sem hsm_id, a Meta apaga todas as versões daquele nome. |
| INVALID_FIELD_MODIFIER | Um campo pedido na leitura do WABA veio com modificador fora do formato aceito. | Use apenas start, end, granularity, dimensions e metric_types, no formato .start(1717200000).end(1719791999). |
| IDEMPOTENCY_KEY_INVALID | O header Idempotency-Key veio com um formato que a API não aceita. | Envie um valor não vazio, com até 255 caracteres, sem espaços nas pontas. |
| IDEMPOTENCY_KEY_REQUIRED | A requisição precisa do header Idempotency-Key e ele não foi enviado. | Inclua o header Idempotency-Key com um valor novo (um UUID serve bem) a cada operação distinta. |
| INVALID_API_KEY | Os dados enviados para criar ou atualizar uma chave de API não passaram na validação. | Confira nome, escopos e data de expiração da chave contra o schema documentado no recurso. |
| INVALID_BODY | O corpo da requisição não é um JSON válido ou não bate com o schema esperado pelo endpoint. | Valide o corpo contra o schema do endpoint antes de enviar e confirme o header Content-Type: application/json. |
| INVALID_PIN | A conclusão da conexão veio com um pin que não tem exatamente 6 dígitos. | Envie o campo pin com os 6 dígitos informados pelo cliente, ou não envie o campo. O PIN não é mais obrigatório no início: o Hub só o pede quando o número ainda não está registrado na Cloud API, e nesse caso a resposta anterior traz pin_required: true. Se o número já tinha verificação em duas etapas ativa, precisa ser o PIN original — divergir devolve pin_incorreto (erro #133005 da Meta) e a sessão aceita uma nova tentativa. |
| INVALID_CALL | O corpo enviado a POST /meta/{phone_number_id}/calls nao passou na validacao: messaging_product precisa ser "whatsapp", call_id precisa ser uma string nao vazia de ate 256 caracteres e action so aceita reject ou terminate. | Envie exatamente {"messaging_product":"whatsapp","call_id":"wacid....","action":"reject"}. As acoes accept e pre_accept exigem sessao SDP e nao passam pela fachada /meta; qualquer campo alem desses tres e descartado. |
| COMANDO_DESCONHECIDO | O identificador do comando administrativo enviado não existe no catálogo de comandos. | Confira o id do comando contra a lista de comandos disponíveis e reenvie com um comando válido. |
| MOTIVO_OBRIGATORIO | Um comando destrutivo foi executado sem o campo motivo preenchido. | Preencha o campo motivo com uma explicação legível sobre o motivo da ação destrutiva. |
| PARAMETROS_INVALIDOS | Os parâmetros enviados para o comando não correspondem ao schema esperado. | Valide os parâmetros contra o schema do comando antes de reenviar. |
| INVALID_CHANNEL | Os dados enviados para criar ou atualizar um canal não passaram na validação. | Revise os campos do canal (nome, número, configuração) contra o schema do recurso Canais. |
| INVALID_CURSOR | O parâmetro cursor de uma listagem paginada veio corrompido ou adulterado. | Use sempre o valor de cursor devolvido pela própria API na resposta anterior, sem editá-lo. |
| INVALID_EXPIRATION | A data de expiração enviada para uma chave de API não está no futuro. | Envie expires_at como uma data ISO 8601 posterior ao momento atual, ou omita para não expirar. |
| INVALID_MEDIA | O arquivo de mídia enviado está ausente, tem um tipo não suportado ou excede o tamanho máximo do tipo. | Confira o tipo MIME e o tamanho do arquivo contra os limites da página de Limites antes de enviar. |
| INVALID_MESSAGE | O corpo da mensagem não corresponde a nenhum tipo de mensagem WhatsApp suportado. | Revise o campo type e os campos específicos do tipo contra o schema de POST .../messages. |
| INVALID_QUERY | Os parâmetros de consulta (query string) de uma listagem não passaram na validação. | Confira nomes, tipos e valores permitidos dos parâmetros de consulta do endpoint. |
| INVALID_SCOPE | A criação de uma chave de API pediu um ou mais escopos que não existem. | Use apenas escopos da lista documentada na tabela de escopo por papel, em Autenticação. |
| INVALID_TEMPLATE | O corpo de envio de template não bate com o schema exigido pela Meta para templates aprovados. | Confira o nome, idioma e os parâmetros de componentes do template contra o que foi aprovado na Meta. |
| INVALID_WEBHOOK | A configuração enviada para criar ou atualizar um webhook (url, eventos, modo de payload) é inválida. | Revise url, event_types e payload_mode contra o schema do recurso Webhooks. |
| INVALID_WEBHOOK_EVENT | Um evento interno tentou ser enfileirado com um tipo que não está em WEBHOOK_EVENT_TYPES, ou com dados incompletos. | Isto normalmente não é causado pelo integrador — se aparecer, cite o x-request-id ao abrir suporte. |
| INVALID_WEBHOOK_PAYLOAD | O payload de um evento de webhook não pôde ser serializado em JSON. | Isto normalmente não é causado pelo integrador — se aparecer, cite o x-request-id ao abrir suporte. |
| WEBHOOK_DNS_FAILED | A URL do webhook não pôde ser resolvida por DNS no momento do cadastro. | Confirme que o domínio do endpoint resolve publicamente antes de cadastrar o webhook. |
| WEBHOOK_URL_NOT_ALLOWED | A URL do webhook usa um esquema, host ou faixa de IP que a política de destino bloqueia. | Use HTTPS, um host público e evite redes internas — veja a seção de bloqueios em Webhooks. |
401
| Código | Quando acontece | Como resolver |
|---|---|---|
| UNAUTHENTICATED | A rota exige uma sessão de administrador da plataforma e nenhuma sessão válida foi enviada. | Autentique-se no painel administrativo antes de chamar a rota. |
402
| Código | Quando acontece | Como resolver |
|---|---|---|
| ACTIVE_SUBSCRIPTION_REQUIRED | A organização não tem uma assinatura paga em estado ativo. | Contrate ou reative um plano em /painel/assinatura antes de repetir a operação. |
| SUBSCRIPTION_REQUIRED | A operação (enviar mensagem, criar webhook) exige assinatura e a organização está sem uma. | Contrate um plano em /painel/assinatura; o envio e a criação de webhook voltam a funcionar assim que a assinatura fica ativa. |
403
| Código | Quando acontece | Como resolver |
|---|---|---|
| FORBIDDEN | A sessão autenticada não tem permissão de administrador da plataforma para a rota. | Esta rota é restrita à equipe interna — não há ação possível do lado do integrador. |
| OWNER_REQUIRED | A operação de cobrança (contratar plano ou adicional) foi chamada por alguém que não é o proprietário da organização. | Peça para o proprietário da organização realizar a operação, ou delegue o papel de owner a quem for executar. |
| PLAN_QUOTA_EXCEEDED | A organização atingiu o limite de canais ou de webhooks do plano contratado. | Remova um recurso existente ou faça upgrade do plano em /painel/assinatura. |
| SESSION_REQUIRED | Um endpoint de gestão de chaves de API foi chamado com uma chave de API em vez de uma sessão do painel. | Gerencie chaves de API autenticado por sessão do painel; uma chave de API não pode criar ou revogar outras chaves. |
404
| Código | Quando acontece | Como resolver |
|---|---|---|
| META_RESOURCE_NOT_FOUND | O recurso pedido não existe na Meta ou não pertence a este canal. | Confirme o identificador e se ele foi criado sob o mesmo número. |
| NOT_FOUND | O identificador do recurso na URL não existe, não pertence à organização autenticada, ou o id não é um UUID válido. | Confirme o id do recurso e que ele pertence à organização da credencial em uso. |
| PHONE_NUMBER_NOT_FOUND | O fluxo de conexão pública não encontrou o número de telefone associado ao link. | Gere um novo link de conexão pública; o número pode ter sido desvinculado da conta da Meta. |
| CUSTOMER_NOT_FOUND | A organização pediu o portal de cobrança sem nunca ter iniciado uma cobrança. | Contrate um plano por POST /api/v1/subscription/checkout antes de abrir o portal. |
409
| Código | Quando acontece | Como resolver |
|---|---|---|
| SEND_RESULT_UNKNOWN | A Meta não confirmou se a mensagem foi aceita e o resultado ficou indeterminado. | Não reenvie às cegas: consulte os logs do canal para saber se a mensagem saiu antes de tentar de novo. |
| CHANNEL_CREDENTIAL_MISSING | O canal não tem uma credencial da Meta armazenada no momento de enviar a mensagem. | Reconecte o canal no painel para renovar a credencial antes de tentar enviar novamente. |
| CHANNEL_NOT_CONNECTED | A operação exige um canal conectado à Meta (com WABA associado) e o canal ainda não está. | Conclua a conexão do canal no painel antes de enviar mensagens ou consultar templates por ele. |
| NOT_PENDING_REGISTRATION | Registro com PIN pedido para um canal que não está no status connected com número vinculado. | Consulte o canal: active já envia; os demais status precisam da conexão pelo link antes do registro. |
| EXTERNAL_ID_CONFLICT | O identificador externo enviado ao criar um canal já está em uso por outro canal ATIVO da organização. Canal excluído não conta: o identificador volta a ficar livre assim que o canal é excluído, então reconectar com o mesmo external_id funciona. | Use um identificador externo diferente, ou reutilize o canal existente em vez de criar um novo. Se você acabou de excluir o canal que usava esse identificador, tente de novo: a exclusão libera o valor. |
| IDEMPOTENCY_KEY_REUSED | A mesma Idempotency-Key foi enviada de novo, mas com um corpo de requisição diferente do original. | Gere uma Idempotency-Key nova para cada corpo de requisição distinto; nunca reaproveite o valor com dados diferentes. |
| OPERATION_IN_PROGRESS | Já existe uma operação em andamento para a mesma Idempotency-Key, ainda não concluída. | Aguarde e repita a requisição depois — a resposta original é devolvida assim que a operação em curso terminar. |
| PHONE_ALREADY_CONNECTED | O número de telefone que o cliente final está tentando conectar já está vinculado a outro canal. | Desconecte o número do canal anterior antes de conectá-lo a um novo, ou use o canal já existente. |
| SUBSCRIPTION_ALREADY_EXISTS | A organização tentou contratar um plano enquanto já tem uma assinatura em aberto. | Cancele ou aguarde a resolução da assinatura existente antes de contratar uma nova. |
| WABA_AMBIGUOUS | A autorização incluiu mais de uma conta do WhatsApp Business e não há como saber qual conectar. | Refaça a conexão compartilhando apenas a conta que será conectada a este canal. |
| CHANNEL_SUSPENDED | A conexão com credenciais foi pedida para um canal suspenso. | Regularize a assinatura ou fale com o suporte para reativar o canal antes de conectá-lo. |
410
| Código | Quando acontece | Como resolver |
|---|---|---|
| MEDIA_EXPIRED | A mídia existiu neste canal, mas a Meta já apagou o arquivo — ela guarda o binário por 30 dias após o envio. | Não repita a requisição: o arquivo não volta. Baixe e guarde a mídia do seu lado assim que o evento chegar pelo webhook. |
413
| Código | Quando acontece | Como resolver |
|---|---|---|
| MEDIA_TOO_LARGE | O arquivo enviado passa do limite aceito pela Meta para aquele tipo de mídia. | Comprima ou reduza o arquivo antes de reenviar. |
| PAYLOAD_TOO_LARGE | O corpo da requisição passa do limite aceito pela API. | Divida o envio em requisições menores. |
| MESSAGE_TOO_LARGE | O corpo da mensagem serializado excede 256 KiB, um limite do próprio CRPRO Hub, imposto antes de repassar a mensagem para a Meta. | Reduza o conteúdo da mensagem para caber no limite de 256 KiB por payload — veja a tabela de Limites. |
| WEBHOOK_PAYLOAD_TOO_LARGE | O payload serializado de um evento de webhook excede o tamanho máximo aceito para entrega. | Isto normalmente não é causado pelo integrador — se aparecer, cite o x-request-id ao abrir suporte. |
415
| Código | Quando acontece | Como resolver |
|---|---|---|
| UNSUPPORTED_MEDIA_TYPE | O content-type enviado não é aceito neste endpoint. | Use um dos tipos suportados pela Meta para o formato em questão. |
422
| Código | Quando acontece | Como resolver |
|---|---|---|
| INVALID_PIN_FORMAT | O corpo do registro não trouxe o campo pin como string de exatamente 6 dígitos. | Envie {"pin":"123456"} — string, só dígitos, seis caracteres. Nada foi enviado à Meta. |
| REGISTRATION_REJECTED | A Meta recusou o registro do número por um motivo que não é PIN, bloqueio, credencial ou instabilidade. | Veja details.meta_code. Com details.reason = on_premises, o número está na API Local e precisa ser desregistrado antes. |
| WABA_MISSING | A autorização concluída na Meta não incluiu nenhuma conta do WhatsApp Business. | Refaça a conexão e, na janela da Meta, selecione (ou cadastre) a conta do WhatsApp Business que será conectada. |
| PHONE_NUMBER_MISSING | A conta da Meta resolvida pelo link de conexão pública não tem número de telefone associado. | Verifique no gerenciador de negócios da Meta se a conta tem um número de telefone configurado, antes de gerar um novo link. |
| META_APP_SECRET_INVALID | A Meta recusou o App Secret informado para o App ID na conexão com credenciais. | Copie de novo o App Secret em Configurações do app > Básico, no painel de desenvolvedores da Meta, e confira se o App ID é do mesmo app. |
| META_TOKEN_INVALID | O Access Token informado na conexão com credenciais está inválido, expirado ou não é reconhecido para o app. | Gere um token novo para o usuário do sistema no Gerenciador de Negócios, com o app informado, e envie as credenciais de novo. |
| META_TOKEN_APP_MISMATCH | O Access Token foi gerado por um app diferente do App ID informado. | Gere o token escolhendo o mesmo app do App ID, ou informe o App ID e o App Secret do app que gerou o token. |
| META_TOKEN_SCOPE_MISSING | O Access Token não tem whatsapp_business_management e whatsapp_business_messaging sobre a WABA informada. | Gere o token do usuário do sistema marcando as duas permissões e atribua a WABA a esse usuário antes de gerar. |
| PHONE_NUMBER_NOT_IN_WABA | O Phone Number ID não aparece entre os números da WABA informada, ou o token não enxerga a WABA. | Confira os dois IDs em WhatsApp > Configuração da API, no painel do app na Meta, e se a WABA está atribuída ao usuário do sistema. |
429
| Código | Quando acontece | Como resolver |
|---|---|---|
| RATE_LIMITED | A requisição excedeu um dos limites de taxa da API — geral, de envio por canal, de teste de webhook ou de conexão pública. | Reduza a frequência de chamadas e recue antes de tentar de novo — veja a orientação de recuo em Limites. |
| PIN_LOCKED | Tentativas de registro demais: pelo limite do Hub (details.locked_by = hub) ou por bloqueio da Meta (details.locked_by = meta). | Aguarde. Com locked_by = hub, respeite retry_after_seconds e o header Retry-After. Com locked_by = meta, a Meta informa o prazo no detalhe do próprio erro, mas o Hub ainda não o repassa (retry_after_seconds vem null); no #133016 a espera é de 72 horas. Cada tentativa nova consome o limite de registro do número. |
500
| Código | Quando acontece | Como resolver |
|---|---|---|
| INTERNAL_ERROR | Ocorreu um erro não previsto no processamento da requisição. | Tente novamente; se persistir, abra um chamado de suporte citando o header x-request-id da resposta. |
502
| Código | Quando acontece | Como resolver |
|---|---|---|
| META_OAUTH_FAILED | A Meta recusou trocar o código de autorização por um token de acesso. | Gere um novo link e refaça a conexão: o código tem validade curta e é de uso único. Se persistir, confira se o endereço de retorno do app na Meta é exatamente https://crprohub.com/connect/retorno. |
| META_UNREACHABLE | A fachada /meta não conseguiu falar com a Meta (falha de rede). A Meta pode ou não ter recebido o pedido. | Não repita um envio de mensagem às cegas: confira pelo status do webhook se ela saiu antes de tentar de novo. |
| META_MEDIA_DOWNLOAD_FAILED | A Meta não entregou o arquivo de uma mídia recebida ao baixar por /meta/_media/{media_id}. | Tente o download de novo em alguns minutos; a mídia fica disponível na Meta por 30 dias. |
| META_RESPONSE_TOO_LARGE | A resposta da Meta veio acima do limite que o Hub aceita processar. | Reduza o intervalo ou a quantidade de itens pedidos e tente de novo. |
| STRIPE_CUSTOMER_FAILED | O provedor de cobrança (Stripe) recusou a criação do cliente ao contratar um plano. | Tente novamente; se persistir, contate o suporte citando o header x-request-id da resposta. |
| STRIPE_CHECKOUT_FAILED | O provedor de cobrança (Stripe) recusou a abertura da sessão de checkout. | Tente novamente; se persistir, contate o suporte citando o header x-request-id da resposta. |
| STRIPE_PORTAL_FAILED | O provedor de cobrança (Stripe) recusou a abertura do portal de cobrança. | Tente novamente; se persistir, contate o suporte citando o header x-request-id da resposta. |
| STRIPE_ADDON_FAILED | O provedor de cobrança (Stripe) recusou a alteração da quantidade de conexões adicionais. | Confira no portal de cobrança se o cartão da assinatura continua válido e tente novamente. |
| STRIPE_PREVIEW_FAILED | O provedor de cobrança (Stripe) não conseguiu calcular o valor proporcional da alteração. | Tente novamente; se persistir, contate o suporte citando o header x-request-id da resposta. |
| META_AUTH_FAILED | A credencial da Meta guardada para o canal está inválida, expirada, sem permissão ou indisponível. | Refaça a conexão do canal pelo link para o Hub receber uma credencial nova. |
| META_UNREACHABLE | A Meta respondeu com instabilidade ou não pôde ser alcançada durante o registro, a conexão com credenciais ou o upload da amostra de header de template (POST /meta/{waba_id}/header_handle). | Tente de novo em instantes. |
| META_SUBSCRIPTION_FAILED | A Meta recusou assinar o app nos webhooks da WABA durante a conexão com credenciais. | Confira se o token tem whatsapp_business_management sobre a WABA e tente de novo. Sem essa assinatura nenhuma mensagem chega. |
| META_INVALID_RESPONSE | A Meta aceitou a chamada de envio, mas devolveu uma resposta sem o identificador da mensagem enviada. | Trate como falha de entrega e tente reenviar; se persistir, confirme o status do número no gerenciador de negócios da Meta. |
| META_SEND_FAILED | A Meta recusou o envio na própria chamada. Muitas recusas não chegam aqui, e sim depois do 202, como message.status com status failed e o código em errors — é o caso do 131049 e do 130472, e costuma ser o do 131026 e do 131047. | Consulte o campo meta_code nos detalhes do erro e o significado do código em /docs/erros/meta antes de reenviar. |
503
| Código | Quando acontece | Como resolver |
|---|---|---|
| HUB_TEMPORARILY_UNAVAILABLE | O Hub ficou momentaneamente sem capacidade (banco de dados) para atender a requisição. | Tente de novo após o header retry-after. Com x-hub-retry-safe: true, o pedido não chegou à Meta e repetir um envio não duplica a mensagem. |
| SEND_ACCEPTED_PENDING_PERSISTENCE | A mensagem foi aceita pela Meta, mas o registro local ainda não foi gravado. | Não reenvie: o registro é reconciliado automaticamente. Consulte os logs do canal para confirmar. |
504
| Código | Quando acontece | Como resolver |
|---|---|---|
| META_TIMEOUT | A Meta não respondeu a tempo à fachada /meta. A Meta pode ter processado o pedido mesmo assim. | Não repita um envio de mensagem às cegas: confira pelo status do webhook se ela saiu antes de tentar de novo. |
| META_UNREACHABLE | A Meta não respondeu a tempo durante o registro ou o upload da amostra de header de template (POST /meta/{waba_id}/header_handle). | Tente de novo em instantes; no registro, consulte o canal antes — ele pode ter sido concluído. |
131049 no details.meta_code de um META_SEND_FAILED, ou no errors de um message.status com falha — estão explicados em códigos de erro da Meta.Códigos de contexto de requisição
Os códigos abaixo não nascem de um endpoint específico — eles vêm da camada de autenticação e contexto de requisição, comum a toda a API, e por isso ficam numa tabela separada.
400
| Código | Quando acontece | Como resolver |
|---|---|---|
| INVALID_FROM | O parâmetro from do filtro de logs veio com uma data que não pôde ser interpretada. | Envie from como uma data ISO 8601 válida, ou omita o parâmetro. |
| INVALID_TO | O parâmetro to do filtro de logs veio com uma data que não pôde ser interpretada. | Envie to como uma data ISO 8601 válida, ou omita o parâmetro. |
| ORGANIZATION_ID_OBRIGATORIO | O usuário autenticado por sessão pertence a mais de uma organização e a requisição não enviou o header x-organization-id. | Envie o header x-organization-id com o id da organização em que a operação deve acontecer. |
401
| Código | Quando acontece | Como resolver |
|---|---|---|
| NAO_AUTENTICADO | Nenhuma sessão de painel nem chave de API válida foi encontrada na requisição. | Envie o header Authorization: Bearer hub_pk_... ou autentique-se no painel antes de chamar a API. |
| CREDENCIAL_INVALIDA | O valor enviado no header Authorization não corresponde a nenhuma chave de API ativa. | Confira se a chave foi copiada por inteiro e se não foi revogada; gere uma nova em /painel/chaves se necessário. |
| CREDENCIAL_REVOGADA | A chave de API usada já foi revogada. | Crie uma nova chave em /painel/chaves; uma chave revogada não volta a funcionar. |
| CREDENCIAL_EXPIRADA | A chave de API usada passou da data de expiração configurada na criação. | Crie uma nova chave em /painel/chaves, com uma expiração mais longa ou sem expiração. |
403
| Código | Quando acontece | Como resolver |
|---|---|---|
| SCOPE_INSUFICIENTE | A credencial (chave de API, token de canal ou sessão) autenticou com sucesso, mas não tem o escopo exigido pelo endpoint. | Use uma credencial com o escopo necessário — veja a tabela de escopo por papel em Autenticação. |
| SCOPE_DELEGATION_FORBIDDEN | A criação de uma chave de API pediu um escopo que a credencial atual não possui. | Peça apenas escopos que a sessão que está criando a chave já tem — não é possível delegar um escopo que não se possui. |
| MEMBERSHIP_AUSENTE | O usuário autenticado por sessão não pertence a nenhuma organização. | Aceite um convite ou crie uma organização no painel antes de chamar a API. |
404
| Código | Quando acontece | Como resolver |
|---|---|---|
| RECURSO_NAO_ENCONTRADO | O header x-organization-id aponta para uma organização à qual o usuário não pertence, ou o recurso pedido é de outra organização. | Confira o id da organização e que o usuário é membro dela; o 404 é deliberado em vez de 403, para não confirmar a existência do recurso a quem não tem acesso. |
429
| Código | Quando acontece | Como resolver |
|---|---|---|
| RATE_LIMITED | A requisição excedeu o limite geral de 120 requisições por minuto por organização e credencial. | Reduza a frequência de chamadas e recue antes de tentar de novo — veja a orientação de recuo em Limites. |
INVALID_FROM e INVALID_TO, nesta última tabela, vêm do filtro de período em /api/v1/logs. Os demais códigos dessa tabela vêm de qualquer endpoint autenticado, antes mesmo da lógica específica do endpoint rodar.