Perspective API shuts down on December 31, 2026.Switch by changing one URL

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 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.

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.