Errors

Pelcro uses conventional HTTP status codes to indicate the success or failure of an API request.

HTTP response status codes are separated into five broad categories, three of which you are more likely to expect while interacting with our API:

2xx – successful – indicates that the request was received, authenticated, understood, validated and processed
4xx – client error – indicates that the request cannot be fulfilled
5xx – returned when server error – the server failed to fulfil an apparently valid request

For 4xx and 5xx errors, some can be handled programmatically, while others need investigation and a human touch. Below is a detailed list of possible HTTP response status code for these categories, along with additional information about how to react to them, if applicable.

400 Bad Request

This status will be returned for any validation errors detected while attempting to process your request. In all cases, the payload will contain details about the reason why the request was rejected.

One example is if you attempt to create a customer without specifying the required email attribute. In this case, you would receive a 404 HTTP status code, with this payload:

{
    "errors": {
        "email": [
            "The email field is required."
        ]
    }
}

Refer to the documentation to see which attribute(s) are required, or if there are any restrictions in place which prevented the request from being validated and processed.

401 Unauthorized

This status will be returned if your request is missing your API key, or if it has expired. Refer to the Authentication section for more information.

403 Forbidden

This status will be returned if your request was authenticated, but your API key prevents you from accessing the endpoint or object. If you're an account collaborator, you should contact the owner of the account.

404 Not Found

This status will be returned if the object you're trying to access does not exist or is not accessible within the scope of your request.

405 Method Not Allowed

This status will be returned if you're trying a GET request on an endpoint which only support POST. To know which HTTP method is supported for any given endpoint, refer to the documentation.

429 Too Many Requests

Our Core API is rate limited, which means that you are allowed to perform a fixed amount of requests within a fixed amount of time. If this occurs, your engineers should handle this gracefully by implementing a retry mechanism. For more information, please refer to the Rate limits section.

500 Internal Server Error

This status will be returned if there was an unexpected error which occurred while processing your request. In other words: it's not you, it's us. If this occurs, our system will automatically trap the error and our engineers will be likely already trying to figure out the issue by the time you contact customer service.

503 Service Unavailable

This status will be returned if our server are temporarily overloaded, or when there is an ongoing maintenance. If this occurs, refer to our status page or try your request again at a later time.