Erros

Toda recusa traz um código estável, em inglês e em snake_case. Programe contra o código, não contra a mensagem: a mensagem pode mudar, o código não.

Na API

O corpo segue o formato abaixo, com o status HTTP do quadro:

{
  "detail": {
    "code": "insufficient_credits",
    "message": "the organization does not have enough available credits"
  }
}

Uma recusa do contrato do cenário acrescenta o código do contrato e o campo culpado:

{
  "detail": {
    "code": "invalid_request",
    "message": "the campaign document breaks its contract",
    "contract_code": "channel_beyond_horizon",
    "field": "canais[1].dia_fim"
  }
}

A recusa age_grid_not_open diz também, em ufs, quais UFs do pedido têm a grade etária fechada:

{
  "detail": {
    "code": "invalid_request",
    "message": "the campaign document breaks its contract",
    "contract_code": "age_grid_not_open",
    "field": "geografia.ufs",
    "ufs": ["PI"]
  }
}

Status	code	Quando	O que fazer
401	invalid_api_key	A chave falta, está errada, expirou ou foi revogada, ou o projeto foi arquivado. Vem com WWW-Authenticate: Bearer.	Confira o cabeçalho Authorization: Bearer bs_….
403	missing_scope	A chave não tem o escopo da rota.	Crie uma chave com o escopo.
429	query_budget_exceeded	Chamadas demais na última hora (Limites). Vem com Retry-After em segundos.	Espere o Retry-After.
403	sem corpo JSON	Chamadas demais em 5 minutos, pela credencial ou pelo endereço de origem (Rajadas).	Espere alguns minutos e espalhe as chamadas.
422	invalid_request	O cenário quebra o contrato; veja contract_code e field.	Corrija o campo; não adianta repetir.
422	release_unavailable	A release, ou uma das UFs nela, não está oferecida.	Escolha uma release e UFs de list_releases.
402	insufficient_credits	A organização não tem saldo para reservar o preço.	Compre créditos e envie de novo.
402	spend_limit_reached	O job passaria do limite de gasto mensal que a organização definiu.	Um admin aumenta o limite em Créditos e uso, ou espere o mês virar.
409	idempotency_key_reused	A Idempotency-Key já criou um job com outro pedido.	Use outra chave para outro pedido.
409	job_not_erasable	O job ainda não terminou: só um job concluido, falhou ou cancelado tem os dados apagados.	Espere o fim do job, ou cancele-o se ele ainda não tem máquina.
409	job_not_cancellable	O job já tem máquina ou terminou.	Nada; um job em máquina termina sozinho.
409	result_not_ready	O job ainda não concluiu, ou concluiu há mais de 365 dias e os dados foram apagados.	Se o job está rodando, espere concluido. Achados apagados não voltam: envie o pedido de novo, que é um job novo e cobrado.
503	results_unavailable	O armazenamento de resultados está fora do ar.	Tente de novo em alguns minutos.
422	finding_unknown	A tabela pedida dos achados não existe.	Use saturacao, alcance_efetivo, alcance_potencial, contribuicao ou elasticidade.
422	tract_output_absent	O job não publicou os eventos por setor censitário: o cenário não pediu saida_por_setor.	Rode de novo com saida_por_setor: true no cenário; os achados e as respostas do job continuam valendo.
422	release_mismatch	Os dois jobs da comparação rodaram em releases diferentes.	Compare jobs da mesma release: a release é a população que os números contam.
422	not_a_simulation	Um dos jobs da comparação é uma calibração.	Leia a calibração em GET /v1/calibracoes/{id} ou com get_calibration.
404	not_found	O job não existe neste projeto.	Confira o id e a chave.
503	tracts_unavailable	O perfil por setor não pôde ser lido agora.	Tente de novo em alguns minutos; o perfil do município segue disponível.
404	municipality_unknown	O código pedido em /v1/municipios/{codigo}/perfil não é de um município da malha do Censo 2022.	Use o código IBGE de 7 dígitos do município.
404	relief_missing	O município não tem relevo nesta versão dos dados (hoje, Fernando de Noronha: o modelo de relevo não cobre a ilha).	O resto da cidade continua disponível; o console mostra a planta sem relevo.
503	relief_unavailable	O relevo não pôde ser lido agora.	Tente de novo em alguns minutos.
503	rainfall_unavailable	A chuva do município não pôde ser lida agora.	Tente de novo em alguns minutos; o resto da cidade segue disponível.
503	diagnosis_unavailable	Os dados por setor (o corte de erro do diagnóstico, as escolas) não puderam ser lidos agora.	Tente de novo em alguns minutos.
403	diagnosis_not_open	O projeto ainda não abriu o diagnóstico da cidade.	Abra a cidade, que é gratuito, e repita.
422	unknown_variable	A variavel pedida não é do diagnóstico.	Use uma variável do resumo da cidade.
422	invalid_growth_request	O pedido do cenário de crescimento quebra o contrato; veja contract_code e field.	Corrija o campo; não adianta repetir.

Um corpo ou cabeçalho fora do formato da rota (sem o envelope {"pedido": …} ou sem Idempotency-Key, por exemplo) é recusado antes de tudo com 422 e o formato de validação padrão: {"detail": [{"loc": …, "msg": …, "type": …}]}.

No MCP

Uma ferramenta recusada responde com isError: true e o texto código: mensagem. Os códigos são os mesmos da API, mais dois do MCP:

Código	Quando
unauthorized	A credencial não vale. Sem credencial nenhuma, o servidor responde 401 antes de qualquer ferramenta, com o endereço do login em WWW-Authenticate.
insufficient_scope	O agente não recebeu o escopo da ferramenta no login. Reconecte e conceda.

Uma recusa do contrato vem como invalid_request: … (contract code channel_beyond_horizon, field canais[1].dia_fim). A de age_grid_not_open diz as UFs fechadas, (contract code age_grid_not_open, field geografia.ufs, closed in PI), e o que fazer: ali, o público vai pelos grupos de 10 anos.

Códigos do contrato

O contract_code de uma recusa invalid_request:

contract_code	O que está errado
unknown_field	Um campo que o contrato não tem.
missing_field	Falta um campo obrigatório, ou ele está vazio.
wrong_type	O valor tem o tipo errado.
duplicate_value	Um valor repetido numa lista.
contract_version_unsupported	versao_contrato não é 3 nem 2 (a 2 é lida como 3).
release_malformed	release fora do formato vX.Y.Z.
family_unknown	familia não é adocao nem recepcao.
ufs_empty	Nenhuma UF em geografia.ufs.
uf_unknown	Uma sigla de UF que não existe.
municipality_malformed	Um código de município sem 7 dígitos.
municipality_outside_ufs	Um município fora das UFs listadas.
ap_malformed	Um código de área de ponderação sem 10 dígitos.
ap_outside_municipalities	Uma área fora dos municípios listados.
audience_axis_refused	Um eixo de público não aceito.
audience_value_unknown	Um valor fora do catálogo do eixo de público.
age_misaligned	Uma faixa etária fora das bordas de 5 anos.
age_ranges_overlap	Faixas etárias que se sobrepõem.
channel_unknown	Um canal fora de digital, tv, radio, exterior.
channel_day_range	Um período com dia_inicio depois de dia_fim, ou fora de 1 a 65.535.
channel_intensity	intensidade fora de (0, 1].
channel_periods_overlap	Dois períodos do mesmo canal se sobrepõem.
channel_beyond_horizon	Um período termina depois do horizonte.
media_in_adoption	Canais num cenário de adoção.
reception_without_media	Um cenário de recepção sem canal.
message_required	Um cenário de recepção sem mensagem.
message_forbidden	mensagem num cenário de adoção.
stim_id_malformed	stim_id sem 32 caracteres hexadecimais.
launch_required	Um cenário de adoção sem lancamento.
launch_forbidden	lancamento num cenário de recepção.
launch_base_unknown	cenario_base fora do catálogo (pix ou calibracao).
launch_calibration_required	cenario_base calibracao sem lancamento.calibracao, o id do job de calibração.
launch_calibration_forbidden	lancamento.calibracao com uma base que não é calibracao.
launch_calibration_malformed	lancamento.calibracao não é um id de job.
launch_day_range	lancamento.dia fora de 1 a 65.535.
launch_beyond_horizon	O lançamento cai depois do horizonte.
horizon_date_malformed	data_inicio fora de AAAA-MM-DD, ou uma data que não existe.
horizon_days_range	horizonte.dias fora de 1 a 65.535.
replicas_range	replicas fora de 1 a 20.
comparison_group_malformed	grupo_comparacao fora do formato (minúsculas, dígitos, _ . -, até 64).
kpis_empty	Nenhum indicador em kpis.
kpi_unknown	Um indicador fora do catálogo da família.
text_too_long	nome com mais de 80 caracteres ou descricao com mais de 500.
electoral_content	Um texto livre com conteúdo eleitoral (Privacidade).
target_finer_than_grid	O público não cabe em nenhuma grade de publicação: faixas de 5 anos (como [25, 34]) num cenário de adoção, ou junto com geografia.aps, faixas_renda, niveis_instrucao ou racas. O campo diz qual. Faixas vizinhas que formam um grupo de 10 anos, como [[20, 24], [25, 29]], cabem na grade principal escritas como [[20, 29]]. Veja a grade etária.
age_grid_not_open	Faixas de 5 anos numa UF em que a grade etária ainda não abriu: hoje, só o Piauí. A recusa traz as UFs fechadas do pedido em ufs.
municipality_not_in_release	Um código de geografia.municipios não está na malha da release.
ap_not_in_release	Um código de geografia.aps não está na malha da release.

No contrato de resposta

Recusados na cotação e no envio, com contract_code e o field da pergunta (veja O contrato de resposta):

contract_code	O que está errado
answer_contract_version_unsupported	contrato_de_resposta.versao não é 1.
answer_contract_empty	O contrato não tem pergunta.
answer_contract_too_many_questions	Mais de 20 perguntas.
question_id_malformed	Um id fora de letras minúsculas, dígitos, _ e -, até 40 caracteres.
question_form_unknown	Uma forma fora de quantos, quando, onde e comparar.
question_measure_unknown	Uma medida que a família do cenário não produz.
question_public_axis_refused	Um eixo de publico que a grade do job não tem.
question_public_value_unknown	Um valor fora do catálogo do eixo.
question_public_with_tracts	Um publico numa pergunta por setor: a tabela por setor não cruza o público.
question_territory_malformed	O territorio não é exatamente um de municipios, setores ou ponto com raio_m (de 50 a 50.000 m), ou um código está fora do formato.
question_territory_needs_tract_output	Uma pergunta por setor num cenário sem saida_por_setor: true.
question_moment_malformed	O momento não é semana (em quantos e onde) nem parte (em quando).
question_week_beyond_horizon	Uma semana depois do horizonte do cenário.
question_share_range	parte fora de (0, 1].
question_order_unknown	ordem fora de maior e menor.
question_variants_malformed	variantes não são dois nomes distintos de variantes do plano.
question_nested_compare	Um comparar dentro de outro.

No cenário de crescimento

Recusados em POST /v1/diagnosticos/{codigo}/crescimento e em estimate_growth, com contract_code e o field (veja O cenário de crescimento):

contract_code	O que está errado
growth_unknown_field	Um campo que o pedido não tem; o field diz qual.
growth_missing_field	Falta versao, municipio ou unidades.
growth_wrong_type	O pedido não é um objeto, ou unidades não é um número inteiro.
growth_version_unsupported	versao não é 1.
growth_municipality_malformed	municipio não é um código IBGE de 7 dígitos, ou não é o município da rota.
growth_units_range	unidades fora de 1 a 20.000 domicílios.
growth_territory_malformed	O pedido não traz exatamente um de poligono e setores, ou um setor está fora do formato de 15 dígitos.
growth_polygon_malformed	Um ponto do poligono não é [longitude, latitude] dentro do Brasil, o contorno tem menos de três pontos distintos ou mais de 1.000, ou não fecha área nenhuma (menos de 1 m²). Repetir o primeiro ponto no fim, como no GeoJSON, é aceito.
growth_polygon_outside_municipality	O centro do poligono não cai em nenhum setor do município.
growth_tract_outside_municipality	Um setor de setores é de outro município.
growth_tract_unknown	Um setor de setores não está nas tabelas do município.

Ao simular a partir de uma calibração

Status	Código	O que está errado
422	calibration_not_found	lancamento.calibracao não é uma calibração deste projeto.
422	spatial_holdout_method_unknown	holdout_espacial.metodo não é plataforma, cliente nem nenhum.
422	spatial_holdout_municipalities	holdout_espacial.municipios só vai com cliente, como lista de códigos IBGE de 7 dígitos, sem repetição.
422	spatial_holdout_outside_series	Um município listado em holdout_espacial.municipios não está na série.
422	spatial_holdout_too_small	A lista do cliente deixa menos de 10 municípios de um dos lados.
409	calibration_not_ready	A calibração ainda não concluiu, ou o resultado dela foi apagado.
422	calibration_release_mismatch	A calibração rodou em outra release.
422	invalid_request, com contract_code calibration_uf_missing	A calibração não escolheu cenário para uma UF do pedido; field é geografia.ufs.

Conferidos na máquina

Estes dependem da release e são conferidos quando o job começa a rodar, não na cotação. Hoje, um pedido que cai num deles termina falhou, e a reserva volta inteira:

Código	O que está errado
uf_not_in_release	A UF não está na release.
uf_without_calibrated_base	A UF não tem o cenário-base calibrado pedido.
calibration_missing	A máquina não recebeu o cenário da calibração. A plataforma confere antes de reservar, então isto indica uma falha nossa.