Errors

Moderation API uses conventional HTTP statuses. Codes in the 2xx range mean success. Codes in the 4xx range mean the request failed because of the information you sent, for example a missing parameter or an invalid API key. Codes in the 5xx range mean a problem on our side.

Response format

Every error response has the same JSON body:

{
  "type": "not_found_error",
  "code": "author_not_found",
  "message": "Author not found",
  "request_id": "h8fkz6kkzoa446ffve37atys",
  "doc_url": "https://docs.moderationapi.com/api-reference/errors#author-not-found"
}

string

required

The broad category of the error. One value per HTTP status. See Statuses.

string

required

Exactly what went wrong. Use this field when your code must react to a specific error. See Error codes. We can add new codes, so handle codes you don’t know by their type.

string

required

A human-readable explanation. Don’t parse it; the text can change.

array

The problems with the request body, when it fails validation. Each issue has a message and the path of the field.

string

required

Identifies the request. Every response, also a successful one, has the same value in the X-Request-Id header. Include it when you contact support.

string

required

A link to the explanation of the code on this page.

A request body that fails validation returns the problems in issues:

{
  "type": "invalid_request_error",
  "code": "validation_failed",
  "message": "Invalid input: expected string, received undefined\n  → at content.text",
  "issues": [
    {
      "expected": "string",
      "code": "invalid_type",
      "message": "Invalid input: expected string, received undefined",
      "path": ["content", "text"]
    }
  ],
  "request_id": "ec9srzy93fuf2brgdl0upgas",
  "doc_url": "https://docs.moderationapi.com/api-reference/errors#validation-failed"
}

Statuses

Status	`type`	Meaning
`400`	`invalid_request_error`	The request is malformed or a parameter is invalid.
`401`	`authentication_error`	The API key is missing, invalid or revoked.
`403`	`permission_error`	The API key can’t do this, or your plan doesn’t allow it.
`404`	`not_found_error`	The resource doesn’t exist, or the API key can’t see it.
`409`	`conflict_error`	The request conflicts with the current state of a resource.
`422`	`invalid_request_error`	The request is valid JSON, but it can’t be processed.
`429`	`rate_limit_error`	Too many requests. See Rate limits.
`500`	`api_error`	Something went wrong on our side. Retry with exponential backoff.

Error codes

400 Bad request

`code`	Meaning
`invalid_request`	A parameter is invalid, or the request body is not valid JSON. `message` says which.
`validation_failed`	The request body doesn’t match the schema. `issues` lists each problem.
`project_id_required`	An organization key called a project endpoint without the `Project-Id` header, and the organization has more than one project.
`project_name_ambiguous`	The `Project-Id` header names a project by name, and more than one project the key reaches has that name. Use the project’s ID.

401 Unauthorized

`code`	Meaning
`missing_api_key`	The `Authorization` header has no API key.
`malformed_api_key`	The `Authorization` header doesn’t contain a key in a valid format.
`invalid_api_key`	The API key doesn’t exist or was revoked.
`unauthorized`	Authentication failed for another reason.

403 Forbidden

`code`	Meaning
`permission_denied`	The API key can’t perform this request.
`account_disabled`	Your organization’s account is disabled.
`quota_exceeded`	Your organization has used all API requests on its plan. Upgrade to continue.
`plan_feature_unavailable`	Your plan doesn’t include this feature.
`plan_limit_exceeded`	The request goes over a limit of your plan.
`organization_key_required`	This endpoint needs an organization API key. See Management API.
`missing_key_permission`	The organization key doesn’t have the permission this endpoint needs.
`project_not_reachable`	The organization key is limited to other projects.

404 Not found

`code`	Meaning
`resource_not_found`	The resource or endpoint doesn’t exist.
`action_not_found`	The action doesn’t exist.
`author_not_found`	The author doesn’t exist.
`queue_not_found`	The review queue doesn’t exist.
`wordlist_not_found`	The wordlist doesn’t exist.
`webhook_not_found`	The webhook doesn’t exist.
`project_not_found`	The project doesn’t exist.
`channel_not_found`	The channel doesn’t exist.

Other statuses

Status	`code`	Meaning
`409`	`resource_conflict`	The request conflicts with an existing resource, for example a key that is already taken.
`422`	`unprocessable_content`	The request is valid, but it can’t be processed.
`429`	`rate_limit_exceeded`	Too many requests. Wait for the seconds in the `Retry-After` header.
`500`	`internal_error`	Something went wrong on our side. Retry with exponential backoff.

Handling errors

Write code that handles every error, so that a failed request doesn’t make your own service unavailable:

Use code for errors you handle in a specific way, for example quota_exceeded. Fall back to type for codes you don’t know.
Retry 429 and 5xx responses with exponential backoff. For 429, wait at least the seconds in the Retry-After header.
Don’t retry other 4xx responses without a change to the request.
Log request_id, so that support can find the request.

API

Account

Moderate

Authors

Actions

Wordlist

Review Queue

Projects

Channels

Webhooks

Analytics

Feedback

Response format

Statuses

Error codes

400 Bad request

401 Unauthorized

403 Forbidden

404 Not found

Other statuses

Handling errors

​Response format

​Statuses

​Error codes

​400 Bad request

​401 Unauthorized

​403 Forbidden

​404 Not found

​Other statuses

​Handling errors

Response format

Statuses

Error codes

400 Bad request

401 Unauthorized

403 Forbidden

404 Not found

Other statuses

Handling errors