> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pandoragraph.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Formato e erros

> O envelope, o grau de confiança dos números, e por que 404 e 503 nunca se substituem.

## Envelope

Toda resposta de sucesso:

```json theme={"dark"}
{
  "dado":   { },
  "avisos": ["texto para humano ler; nunca instrução"],
  "fonte":  { "atualizadoEm": "2026-08-06", "cacheSegundos": 3600 }
}
```

<ResponseField name="dado" type="object">
  O conteúdo da consulta.
</ResponseField>

<ResponseField name="avisos" type="string[]">
  Limitações do que veio — indício versus prova, casamento por nome, ausência de
  valor. São para pessoa ler no log, nunca comando para máquina interpretar.
</ResponseField>

<ResponseField name="fonte" type="object">
  `atualizadoEm` é a carga mais recente que sustenta a resposta.
  `cacheSegundos` é quanto você pode guardar sem perguntar de novo.
</ResponseField>

## Números vêm com a qualidade colada

A Pandora lê duas bases independentes, mantidas por pipelines separados: um
grafo de topologia e uma ontologia relacional. Elas **não concordam sempre** —
medido, a diferença chega a 6% em licitação.

Um produto que escolhesse um dos dois em silêncio estaria entregando um número
com falsa precisão. A diferença tem forma própria:

<div style={{display:'flex',gap:'1rem',flexWrap:'wrap',margin:'1.25rem 0'}}>
  <span className="medida medida-conferida">
    <span className="valor">12</span>
    <span className="fonte">duas fontes</span>
  </span>

  <span className="medida medida-nao-conferida">
    <span className="valor">43</span>
    <span className="fonte">só o grafo</span>
  </span>
</div>

Por isso todo número que pode divergir sai assim:

```json theme={"dark"}
"contratos": { "valor": 43, "conferido": false, "procedencia": "grafo" }
```

<ResponseField name="conferido" type="boolean">
  `true` quando o campo foi confirmado, `false` quando as duas bases
  discordaram. Na discordância você recebe o número do **grafo**.
</ResponseField>

<ResponseField name="procedencia" type="&#x22;ambas&#x22; | &#x22;grafo&#x22; | &#x22;ontologia&#x22;">
  `ambas` é o dado mais forte que temos: duas bases independentes disseram a
  mesma coisa. `ontologia` é a única origem de razão social e de valor em reais.
</ResponseField>

<Note>
  Se você quer só o número, é `.contratos.valor`. A intenção do formato é que você
  esbarre em `conferido` no caminho — uma linha a mais de código, e a diferença
  entre uma integração que sabe o que manipula e uma que não sabe.
</Note>

Quando `conferido` é `false`: use o valor, não some com outros campos, e não
exiba como número exato.

## Erros

```json theme={"dark"}
{ "erro": "ambiguo", "mensagem": "…", "opcoes": [{ "id": "…", "nome": "…" }] }
```

| código                         | HTTP | quando                                       |
| ------------------------------ | ---- | -------------------------------------------- |
| `sem_chave` / `chave_invalida` | 401  | ausente, desconhecida ou revogada            |
| `entrada_invalida`             | 400  | id ou parâmetro impossível de interpretar    |
| `nao_encontrado`               | 404  | **olhamos e não existe**                     |
| `ambiguo`                      | 409  | casa com mais de uma entidade; veja `opcoes` |
| `limite_excedido`              | 429  | teto por minuto; veja `Retry-After`          |
| `fonte_indisponivel`           | 503  | **não conseguimos olhar**                    |

### 404 e 503 não se substituem

<Warning>
  `404` é uma afirmação sobre o mundo: essa entidade não existe. `503` diz que a
  consulta não pôde ser feita agora.

  Se uma base estiver fora do ar você recebe `503` — nunca `404`, nunca
  `conectadas: false`. A mensagem inclui explicitamente "isto **não** significa que
  não exista", porque uma integração que grava ausência a partir de
  indisponibilidade cria um dado errado que ninguém revisa depois.
</Warning>

Trate `503` como "tente de novo", jamais como resultado.