Errors

When the API refuses a request it answers with a status of 400 or above and the same JSON shape on every endpoint. Your code reads code. A person reads message.

A request to create a webhook endpoint without a url, for example:

{"error": {"code": "validation_error","message": "The request could not be validated","details": [{ "field": "url", "message": "Invalid input: expected string, received undefined" }],"request_id": "req_790d3c81de2a406395e413a56865b6f1"}}

Error codes

The pages on authentication, idempotency, rate limits and checks cover their own codes in depth. Statuses and failures covers what a moderation can answer without an HTTP error, such as status: "invalid".

Validation errors

A 422 carries one entry in details per problem.

• field is the path of the value, joined with dots: url, event_types.0, items.3.input. A problem with the body as a whole reads body, and one with the query string reads query.
• message says what is wrong with it. Most messages come from the schema check and can change wording, so match on field.

Some values are checked after the schema, and then message at the top says what was refused: url: Target resolves to a private address (localhost).

A submission that fails a template's own validation is not an HTTP error. It answers 200 with a moderation whose status is invalid.

Server errors

A fault on Infrared's side answers 500 and reads the same, whatever failed:

{
  "error": {
    "code": "internal_error",
    "message": "Something went wrong on our side",
    "details": [],
    "request_id": "req_660bf6f2a3dd480e8a20bec694ba90ea"
  }
}

The cause is logged on Infrared's side under the request id. Retry the request, and send the id to support if it keeps failing.

A few requests answer 500 today where you would expect a 4xx:

• A body that is not UTF-8, or that uses a Content-Encoding the API cannot read.
• A reason longer than 255 characters on the author endpoints that block, suspend or enable. Keep it to 255.
• A filter value outside its list on two lists: status on GET /v1/moderations and priority on GET /v1/queue.

Errors inside a batch

One bad item does not fail a batch. The batch answers 200 or 202, and the item that was refused takes its place in data as an error:

{"object": "error","index": 1,"error": { "code": "template_not_found", "message": "Template old-listing not found", "details": [] }}

index is the item's position in the request, counted from 0. The entry has no request_id of its own: use the one of the batch.

What to retry

When a moderation carried an Idempotency-Key, a refusal such as 402, 404 or 422 is stored under it. Once the cause is fixed, send the moderation with a new key, or the stored refusal comes back.

Next

• Statuses and errorsThe five statuses a moderation can have and every error the moderation endpoints return, with the HTTP status, the code and what to do next.
• IdempotencySend an Idempotency-Key when you create a moderation, and a retry returns the first answer in place of a second moderation and a second charge.
• Rate limitsEach API key may send a set number of requests a minute, by plan. Every response says where the key stands, and a 429 says how long to wait.