Errors

The Paddle Invoice API uses standard HTTP response codes to let you know when something’s wrong. It also returns some useful information to help you troubleshoot.

Errors generally return a 4xx response code.

Though rare, you may get a 5xx response code. This means that there’s a problem with the Paddle API rather than your code. Try your request later, or check our status page.

Error format

When you have an error, the API returns an error key along with the HTTP status code. It doesn’t return a data key like it does with success responses.

For example:

{
  "error": {
    "type": "request_error",
    "code": "authentication_missing",
    "detail": "No authentication information was provided",
    "documentation_url": "https://developer.paddle.com/errors/bad_request_authentication"
  }
}

Where there are validation errors, the error includes an array of errors to let you know which fields failed validation and how to fix.

For example:

{
  "error": {
    "type": "request_error",
    "code": "product_invalid_parameter",
    "detail": "Product validation errors",
    "documentation_url": "https://developer.paddle.com/errors/bad_request_product_invalid_parameter",
    "errors": [
      {
        "field": "name",
        "message": "max length of 200 exceeded, provided value length 220"
      },
      {
        "field": "billing_mode",
        "message": "value must be one of: quantity or usage, got 'quantity2'"
      }
    ]
  }
}

Error types

request_error

Most errors should return request_error as the type. This means that something’s wrong with the request that you made. You can use the code, detail, and documentation_url to troubleshoot.

api_error

Where the type is api_error, something is wrong with the Paddle API. Try your request later, or check our status page.

Error codes

HTTP response codes

The Paddle API uses standard HTTP response codes to let you know when something’s wrong.

Response	Meaning	Description
400	Bad request	Something’s not right with your request. This usually means the JSON sent isn’t properly formatted, or you’re missing a required parameter.
401	Unauthorized	You didn’t include an API key, or your API key is no longer valid.
403	Forbidden	Your API key is valid, but you don’t have permission to perform that request.
404	Not found	You requested something that doesn’t exist, or used a URL that’s not recognized.
422	Unprocessable entity	Something’s not right with your request. This usually means that you’ve included invalid fields. Use custom_data to include additional information.
429	Too many requests	You’ve sent too many requests to the API and hit a rate limit.

Error code

Along with the HTTP response code, the Paddle API returns a code in the error key. This gives you a little more context.

Error Code	Description
authentication_missing	You didn’t include an API key in the header, or your API key is no longer valid.
authentication_malformed	You included a Bearer value, but the API couldn’t understand it. Check the token is correct.
invalid_token	Your Bearer value is in the correct format, but it is not valid.
bad_request	Something’s not right with your request. This usually means the JSON sent isn’t properly formatted, or you’re missing a required parameter.
not_found	You requested something that doesn’t exist, or used a URL that’s not recognized.
forbidden	Your API key is valid, but you don’t have permission to perform that request.
internal_error	There’s a problem with Paddle’s API.
service_unavailable	There’s a problem with Paddle’s API.
not_implemented	The action or resource you requested is not available. This may be because you’re using an incorrect API version.
product_invalid_parameter	Something’s not right with one of the parameters you passed. Check the returned errors for information on how to fix.