Errors

In this guide, we will talk about what happens when something goes wrong while you work with the API.

You can tell if your request was successful by checking the status code when receiving an API response.

Status codes

Here is a list of the different categories of status codes returned by the Protocol API. Use these to understand if a request was successful.

Name
2xx
Description
A 2xx status code indicates a successful response.
Name
4xx
Description
A 4xx status code indicates a client error — this means it's a you problem.
Name
5xx
Description
A 5xx status code indicates a server error — you won't be seeing these.

Error types

When a request is unsuccessful, we return a 4xx or 5xx status code.

Name
message
Type
string
Description
A human-readable description of what went wrong.

Error response

{
    "message": "string",
}

Validation errors

Validation errors (status 422) include an additional field:

Name
message
Type
string
Description
A human-readable description of what went wrong.
Name
errors
Type
dictionary[string, array]
Description
A detailed description of each field that failed validation.

Validation error

{
    "message": "string",
    "errors": {
        "property1": [
            "string"
        ],
        "property2": [
            "string"
        ]
    }
}

When creating a task, an Unprocessable Content (status 422) can also be returned when the request content is not approved by our content filters. When this error is returned a code parameter is included to help distinguish it from generic form submission errors.

Name
message
Type
string
Description
A human-readable description of what went wrong.
Name
code
Type
string
Description
A unique identifier for the error.

Content Policy Violation

{
    "message": "The content violates our policy",
    "code": "content_policy_violation"
}

Payment Required Errors

Certain endpoints require an active subscription to be used, in which case a HTTP 402 Payment Required error is returned. This status code is also returned when trying to perform an action that requires credits, but you do not have sufficient credits in your account.

Name
message
Type
string
Description
A human-readable description of what went wrong.

Payment Required 402

{
    "message": "An active subscription is required to perform this action"
}