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
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.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
For5xx and 429 errors, implement exponential backoff with jitter.
Non-retryable errors
For4xx 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
For401 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_idfor troubleshooting. - Alert on
5xxerrors that persist for more than 5 minutes. - Flag
403errors as a configuration issue and review your OAuth scopes. - Track
429patterns 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.