# Consultas que demoram

# Consultas que demoram

Algumas consultas não terminam dentro da requisição. Nesses casos o `POST` responde na hora, o
processo segue em segundo plano, e você acompanha por `GET /status`.

## Como saber quais são

O campo **`assincrono`** de cada item do `GET /catalog`. Não presuma pela categoria: consulte o
catálogo.

## O que o `POST` devolve

```json
{
  "success": true,
  "async": true,
  "consultation_id": "3f1c9a2e-...",
  "status": "processing",
  "environment": "production"
}
```

:::caution
O status HTTP é **200**, não `202`. O que distingue este caso é o campo **`async`** — é nele que
você deve ramificar, não no status.
:::

## Acompanhando

```bash
curl -X GET "https://api.consultas.us/status?consultation_id=3f1c9a2e-..." \
  -H "X-API-Key: SUA_CHAVE"
```

O parâmetro chama-se **`consultation_id`**. Não é `id`.

`GET /status` **não cobra**. Chame quantas vezes precisar.

### Enquanto processa

```json
{ "success": true, "status": "processing", "consultation_id": "3f1c9a2e-..." }
```

Não há resultado parcial: enquanto não há desfecho, não há o que ler.

### Quando termina

```json
{ "success": true, "status": "completed", "consultation_id": "3f1c9a2e-...", "result": { } }
```

### Quando falha

```json
{ "success": true, "status": "failed", "consultation_id": "3f1c9a2e-...", "error": "…", "refunded": 5.9 }
```

`refunded` diz quanto voltou para a sua carteira. Falha depois da cobrança é estornada.

## Se o `/status` responder 503

`503` com `code: "STATUS_UNAVAILABLE"` é indisponibilidade temporária **do acompanhamento**, não da
sua consulta. Ela continua rodando — tente de novo em alguns segundos.

Não trate isso como problema de credencial e não reenvie o `POST`: o reenvio cobraria outra vez.