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
429and503responses carry aretry-afterheader with the seconds to wait. Wait that long, then retry.503 model_unavailableand503 capacity_pausedare short. Rules, cached results and test keys keep working during them.- Don't retry
4xxerrors other than429: 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.