Skip to main content
This page covers how to handle errors at each stage of a moderation request — submission, processing, and result retrieval.

Error types

Transient vs permanent errors

Transient errors are temporary and safe to retry:
  • 429 RATE_LIMITED — wait and retry (see rate limiting)
  • 500 INTERNAL_ERROR — server-side failure; retry with backoff
  • 503 — service degraded; retry with backoff
Permanent errors should not be retried without changing something:
  • 400 INVALID_REQUEST — fix the request (missing fields, invalid file format, file too large)
  • 401 UNAUTHORIZED — provide a valid API key
  • 403 ACCOUNT_TERMINATED — contact support; the account cannot be recovered programmatically

Retrying submissions

For 5xx errors, use exponential backoff to avoid overwhelming the API during an outage.

Handling failed jobs

A job with status: "failed" means processing encountered an unrecoverable error after the job was accepted. is_prohibited will be null.
Failed jobs should be resubmitted as new requests. The original job_id cannot be retried.

Rate limit recovery

When you receive a 429 RATE_LIMITED response, the error body includes details:
Wait before retrying. The standard rate limit window is 60 seconds. See rate limiting for limits by tier.

Checking job status after a timeout

If your application restarts or a webhook is missed, poll the job status endpoint to recover in-flight jobs: