Errors

The API reports a failure through the HTTP status code. Most error responses carry a JSON body with the structure below; 401, 403 and 429 do not.

Error body

Field	Description	Type
status	The HTTP status code of the response	Integer
error	The error code, listed under Status codes	String
messages	One or more entries describing the error	Array

Each entry in messages has:

Field	Description	Type
message	A description of the error, in Brazilian Portuguese	String
attribute	The parameter, field or rule that caused the error. Absent on record_not_found and standard_error	String
model	The type of resource that was not found, e.g. Order. Only on record_not_found, and not always present	String
extra	Context about the operation that failed. Only on unprocessable_action; an object or an array, depending on the operation	Object or Array

message is written for people. To handle an error in code, use error and attribute.

Status codes

Status	error	Meaning
400 Bad Request	parameter_missing	A required parameter is missing. attribute names it
400 Bad Request	unprocessable_action	A business rule rejected the request. attribute names the rule
401 Unauthorized	—	The token is missing, invalid or disabled. The body is an empty JSON object, {}. See Authentication
403 Forbidden	—	Requests from your IP address are blocked. The body is the plain text Forbidden. Contact support
404 Not Found	record_not_found	The resource does not exist, or your token cannot access it
422 Unprocessable Content	record_invalid	The data failed validation. messages has one entry per failed validation, so a field can appear more than once
422 Unprocessable Content	unprocessable_action	A business rule rejected the request. A few rules answer 422 instead of 400, e.g. enabling an offer that is already enabled
429 Too Many Requests	—	A rate limit was exceeded. The body is empty. See Rate Limits
500 Internal Server Error	standard_error	An unexpected server error. Contact support

Examples

parameter_missing

POST /external_api/v1/orders without offer_id:

{
    "status": 400,
    "error": "parameter_missing",
    "messages": [
        {
            "attribute": "offer_id",
            "message": "Parâmetro obrigatório ausente ou inválido."
        }
    ]
}

unprocessable_action

POST /external_api/v1/orders without the signature object:

{
    "status": 400,
    "error": "unprocessable_action",
    "messages": [
        {
            "attribute": "signature",
            "message": "O objeto signature é obrigatório e deve conter remote_ip e user_agent.",
            "extra": {
                "offer_id": "8dd4fffd-e1b3-503f-a7f2-963c6d32c0cd",
                "controller": "external_api/v1/orders",
                "action": "create"
            }
        }
    ]
}

Unauthorized

A request without a valid token:

{}

record_not_found

GET /external_api/v1/orders/:id with an ID that does not exist:

{
    "status": 404,
    "error": "record_not_found",
    "messages": [
        {
            "message": "Não foi possível encontrar um registro com os parâmetros enviados.",
            "model": "Order"
        }
    ]
}

record_invalid

POST /external_api/v1/webhooks with a url that is not https:

{
    "status": 422,
    "error": "record_invalid",
    "messages": [
        {
            "attribute": "url",
            "message": "Url não é uma URL válida"
        }
    ]
}

standard_error

{
    "status": 500,
    "error": "standard_error",
    "messages": [
        {
            "message": "Ocorreu um erro inesperado. Tente novamente mais tarde."
        }
    ]
}