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 afterretryAfterseconds.not_available_yet: the moderation type cannot be served right now.retryAfterisnull; 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.