Skip to main content
All Invoicing API error responses follow a consistent structure. This guide covers error codes, retry guidance, and client handling patterns.

Canonical error object

All error responses follow this structure.

Field descriptions

Error taxonomy

The following table lists all error codes, their HTTP status, and whether the request can be retried.

Common error scenarios

The following scenarios show common errors and how to resolve them.

Create an invoice with an invalid merchant account

To resolve this, verify the invoicer’s email address and PayPal account status. Confirm the account isn’t suspended or limited.

Record a payment on a PayPal-processed invoice

If you try to record a payment on an invoice that PayPal has already processed, you receive the following error.
To resolve this, verify the invoice status using GET. If the status is already PAID or PARTIALLY_PAID, PayPal automatically records the payment. Use the record payment endpoint only for offline payments received through channels other than PayPal.

Client handling guidance

The following guidance covers how to handle different error types in your integration.

Retryable errors

For 5xx and 429 errors, implement exponential backoff with jitter.

Non-retryable errors

For 4xx errors other than 401 and 429, return the error to the user with the debug_id. Don’t retry. Use the details array to provide field-level feedback.

Authentication errors

For 401 errors, refresh the access token and retry the request once. If the second attempt also returns 401, return the error to the user.

Alerting guidance

  • Log all errors with debug_id for troubleshooting.
  • Alert on 5xx errors that persist for more than 5 minutes.
  • Flag 403 errors as a configuration issue and review your OAuth scopes.
  • Track 429 patterns to understand API usage and adjust request rates.

Troubleshooting

Find solutions to common integration issues with the PayPal Invoicing API.

Quick start using Invoicing API

Create and send your first invoice using the PayPal Invoicing API.