# Handling outages

Your users shouldn't notice when a check can't run. Decide what your app does if Spamgone is slow or unavailable, and build it in from the start.

## Set a timeout

Checks usually answer in a fraction of a second. Give each call a timeout of about 3 seconds, so a slow answer never holds up a message.

## Fail open, or hold for review

When a check fails or times out, most apps let the message through (fail open) and check it again later, or hold it for review. Blocking everything during an outage usually hurts more than a little spam.

## Retry what the API tells you to

- `429` and `503` responses carry a `retry-after` header with the seconds to wait. Wait that long, then retry.
- `503 model_unavailable` and `503 capacity_paused` are short. Rules, cached results and test keys keep working during them.
- Don't retry `4xx` errors other than `429`: they mean the request needs fixing. The [error reference](/docs/errors) says how.

## Make retries safe

Send an `Idempotency-Key` header with each `POST`. A retry with the same key and body returns the first answer instead of checking again, so nothing is counted twice.

```bash
curl -X POST https://spamgone.dev/v1/checks \
  -H "Authorization: Bearer $SPAMGONE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: message-48151623" \
  -d '{"text": "see you at practice"}'
```

## Know when something is wrong

Every response has an `x-request-id` header. Log it next to the message, so you can find the exact call in the dashboard's Logs, and give it to us if you contact support.
