Errors

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

Each error includes a documentation_url pointing to the reference page for that error, so you can quickly find the cause and fix.

HTTP status codes

Errors generally return a 4xx response code.

Though rare, you may get a 5xx response code. This means there's a problem with the Paddle API rather than your request. Retry with exponential backoff, or check our status page if the issue persists.

For 429 responses, see Rate limiting for how to back off and retry.

Error object

When you encounter an error, the API returns an error object rather than a data object or array. For example:

{
  "error": {
    "type": "request_error",
    "code": "not_found",
    "detail": "Entity pro_01gsz97mq9pa4fkyy0wqenepkz not found",
    "documentation_url": "https://developer.paddle.com/errors/shared/not_found"
  },
  "meta": {
    "request_id": "9346b365-4cad-43a6-b7c1-48ff6a1c7836"
  }
}

Validation error object

When making requests, all fields are checked against the API reference to make sure they're valid. If a value for a field fails validation, Paddle includes an array of errors to let you know which fields need your attention.

For example:

{
  "error": {
    "type": "request_error",
    "code": "invalid_field",
    "detail": "Request does not pass validation.",
    "documentation_url": "https://developer.paddle.com/errors/shared/invalid_field",
    "errors": [
      {
        "field": "active",
        "message": "must be provided as part of the request"
      },
      {
        "field": "description",
        "message": "maximum length of 256 exceeded. provided value length 653"
      }
    ]
  },
  "meta": {
    "request_id": "9346b365-4cad-43a6-b7c1-48ff6a1c7836"
  }
}

Request ID

Every response includes a meta.request_id. Log it alongside the error and include it when you contact Paddle support. It's the fastest way for support to locate the request in our logs.