Concepts / Errors
Concepts

Errors

Detectivision API errors: HTTP status codes, the error body and its codes, which requests to retry and how, and when a failed check is charged.

On this page

The API uses standard HTTP status codes. 2xx is success; 4xx means the request must change before it can succeed; 5xx means try again later. You are never charged for an error, and only a completed result is charged (a partial result is free).

Status codes#

HTTP Meaning Retry?
200 The check ran. Read status (completed or partial). —
201 A live session started. —
400 The request or its input cannot be used, or there are not enough credits. Only after fixing it.
401 Missing, invalid or expired API key. No.
402 Live sessions: not enough live stream credits. After adding credits.
403 The key's permission does not allow this. No.
404 Not found (a censored copy, a session, a frame). No.
409 Live sessions: the session is not in a state that allows this. No.
413 Too large: a moderation request's file (an image over 10 MB, a video over 20 MB) or its image in base64 (over 10 MB), its JSON over 14 MB, other JSON over 100 KB, a frame over 2 MB. No.
415 Live frames: not JPEG, PNG or WebP. No.
429 Too many requests in a minute (see Rate limits), 50 async checks already waiting, or live frames sent faster than twice the session's fps. After Retry-After seconds.
500 Unexpected error on our side. Yes, with backoff.
503 Checks are temporarily unavailable, or the type cannot be served right now. Yes if temporarily_unavailable.

Rate limits#

The limits below count over a minute. Over one, the answer is 429 with a Retry-After header (in seconds) and the usual error body:

{ "error": "too_many_requests", "message": "Too many requests. Try again in a minute." }
What Limit
Calls with one API key 1,200 a minute
Calls from one address 1,200 a minute
Live sessions started by one account 20 a minute
Actions taken through the API 60 a minute (Metadata and actions)

Live frames are not counted against the key: a session takes frames at up to twice its fps.

Apart from those, an account can have at most 50 async checks waiting at once. This limit counts the checks waiting, not the calls of a minute: one more gets the same 429, with Retry-After: 60 and the message Too many checks are waiting: at most 50 per account. Send more once some have run.

Your credits limit how much you can check; these limits only set the pace. If you need more, contact us.

Error bodies#

Every error has the same shape: error, a stable code to branch on, and message, what went wrong in a sentence for people.

{ "error": "invalid_input", "message": "the URL does not point to an image" }

A refused request body also lists each problem in details:

{
  "error": "invalid_request",
  "message": "Invalid moderation request",
  "details": [{ "code": "invalid_value", "path": ["type"], "message": "Invalid moderation type" }]
}

Branch on error, never on message: messages may be worded better over time, codes stay.

Error codes#

error HTTP Meaning
invalid_request 400 A field is missing, has the wrong type or is out of range, in a JSON body or a form (a form without its file, or with input). details lists each problem.
invalid_input 400 The input cannot be used (not an image, an empty file, base64 that is not valid, a downloaded image over 10 MB, an empty frame…). message says why.
video_too_long 400 The video is longer than one check takes: 300 frames at the fps asked (5 minutes at fps: 1), or more than 80 seconds of processing. Send it in shorter parts. charged says what the part already read cost, if anything (at most five units).
audio_too_long 400 The recording is longer than one check takes: 5 minutes. Send it in shorter parts. Refused before it is heard when its file says its length: nothing is charged. A file that says less than it holds is heard first, and charged is what its minutes cost.
audio_length_unknown 400 The recording's file does not say how long it is, and it is large enough to be longer than one check. Send it as WAV, MP3, M4A, OGG, WebM or FLAC with a standard header, or in shorter parts. Nothing is charged.
invalid_flags 400 A flag the type does not check. message lists the ones it does.
content_declined 422 The content could not be checked: the check declined to look at it. Final; asking again gets the same answer. Nothing is charged.
invalid_metadata 400 metadata is not a JSON object of at most 16 KB.
insufficient_quota 400, 402 Not enough credits for this type (live sessions: 402). See Credits and billing.
unauthorized 401 Missing, invalid or expired API key, or the account is not active.
forbidden 403 The key's permission does not allow this.
insufficient_scope 403 An app's access token was not given access to this.
not_found 404 No such request, session, frame or endpoint.
conflict 409 Live sessions: the session is not in a state that allows this.
payload_too_large 413 Too large: a file (an image over 10 MB, a video over 20 MB) or an image in base64 (over 10 MB), a moderation request's JSON over 14 MB, other JSON over 100 KB, a frame over 2 MB. message says which, for example the video is larger than 20 MB.
unsupported_media_type 415 Live frames: not JPEG, PNG or WebP.
too_many_requests 429 Over a rate limit, or 50 async checks already waiting. Wait Retry-After seconds.
internal_error 500 Unexpected error on our side.
temporarily_unavailable 503 No check can run right now. Retry after Retry-After seconds.
not_available_yet 503 The moderation type cannot be served right now. Do not retry; Service status shows each type's state.

400 on /api/v1/moderation#

error message Fix
invalid_request Invalid moderation request (see details) A field is missing, has the wrong type or is out of range. In a form: the file goes in file, and input belongs in a JSON body.
invalid_input e.g. the image is not valid base64 The input cannot be used. The message says why; see Text, Image, Video.
invalid_input Live streams are moderated in sessions: … Use live sessions for streams.
invalid_flags e.g. image_moderation does not check insult. Flags it checks: … Send only the flags GET /api/v1/flags lists for the type.
invalid_metadata why it was refused See Metadata and actions.
insufficient_quota e.g. Not enough credits for image_moderation. Not enough credits for this type. See Credits and billing.

Note

What can be told without downloading the input comes first: a text's length, a URL's form, fps, an upload's type and size. Credits come before any download, so an account without credits for a type gets insufficient_quota even for an input that would be refused once downloaded.

503: unavailable#

When no check can run right now, the API answers 503 with a Retry-After header:

HTTP/1.1 503 Service Unavailable
Retry-After: 60
Content-Type: application/json

{
  "error": "temporarily_unavailable",
  "message": "Image moderation is temporarily unavailable.",
  "status": "unavailable",
  "type": "image_moderation",
  "charged": 0,
  "retryAfter": 60,
  "statusUrl": "https://api.detectivision.ai/api/v1/status"
}

error is either:

  • temporarily_unavailable: retry after retryAfter seconds.
  • not_available_yet: the moderation type cannot be served right now. retryAfter is null; do not retry. Service status shows each type's state.

Live session 503s have the same error codes, without retryAfter: retry temporarily_unavailable after a minute, never not_available_yet.

Retrying#

Retry 503 (temporarily_unavailable), 500 and network errors, a few times, waiting between attempts. Never retry 400, 401, 403 or 404 without changing the request.

import os, time, requests

def moderate(payload, attempts=4):
    for attempt in range(attempts):
        try:
            r = requests.post(
                "https://api.detectivision.ai/api/v1/moderation",
                headers={"Api-Key": os.environ["DETECTIVISION_API_KEY"]},
                json=payload,
                timeout=180,
            )
        except requests.RequestException:
            r = None
        if r is not None and r.status_code < 500:
            r.raise_for_status()  # 4xx: fix the request
            return r.json()
        if r is not None and r.status_code == 503 and r.json().get("error") == "not_available_yet":
            raise RuntimeError(r.json()["message"])
        wait = int(r.headers.get("Retry-After", 0)) if r is not None else 0
        time.sleep(wait or 2 ** attempt)
    raise RuntimeError("Detectivision is unavailable, try again later")
async function moderate(payload, attempts = 4) {
  for (let attempt = 0; attempt < attempts; attempt++) {
    let res;
    try {
      res = await fetch("https://api.detectivision.ai/api/v1/moderation", {
        method: "POST",
        headers: { "Api-Key": process.env.DETECTIVISION_API_KEY, "Content-Type": "application/json" },
        body: JSON.stringify(payload),
        signal: AbortSignal.timeout(180_000),
      });
    } catch {
      res = null; // network error: retry
    }
    if (res && res.status < 500) {
      const body = await res.json();
      if (!res.ok) throw new Error(`${res.status} ${body.error}: ${body.message}`);
      return body;
    }
    if (res?.status === 503) {
      const body = await res.json();
      if (body.error === "not_available_yet") throw new Error(body.message);
    }
    const wait = Number(res?.headers.get("Retry-After")) || 2 ** attempt;
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
  throw new Error("Detectivision is unavailable, try again later");
}

Authentication errors#

See Authentication.