Troubleshooting Invoicing API

The PayPal Invoicing API returns specific error codes and messages to help you troubleshoot integration issues.

Error response format

All Invoicing API errors follow this structure:

{
    "name": "INVALID_REQUEST",
    "message": "Request is not well-formed, syntactically incorrect, or violates schema.",
    "details": [
    {
        "description": "Payment method is missing.",
        "field": "/method",
        "issue": "MISSING_REQUIRED_PARAMETER",
        "location": "body"
    }
    ],
    "links": [
    {
        "href": "https://developer.paypal.com/docs/limited-release/invoicing/#errors",
        "rel": "information_link"
    }
    ],
    "debug_id": "04228dda78114"
}

API errors

PayPal returns HTTP 4XX status codes if something passes in the request has an error. 5XX status codes appear when something is wrong on our end with a server or service. For more information, see Handling API responses when integrating with PayPal APIs.

HTTP code	Error name	Message	Details
400	INVALID_REQUEST	Invalid request	One or more validation errors have occurred.
401	AUTHENTICATION_FAILURE	Authorization error occurred	Authorization error occurred. Check your credentials.
404	RESOURCE_NOT_FOUND	Resource not found	The resource requested is not found in the system.
422	UNPROCESSABLE_ENTITY	Invoicing business error	A detailed error message is passed in the message field.
429	RATE_LIMIT_REACHED	Too many requests and user is blocked due to rate limiting	The rate limit for the user, application, or token exceeds a predefined value.
500	INTERNAL_SERVER_ERROR	Internal service error	Resend the request at another time.

Authorization errors

HTTP code	Issue	Message	Common cause	Affected fields
403	NOT_AUTHORIZED	Authorization failed due to insufficient permissions	Invalid access token or account permissions	invoiceId, templateId
403	PERMISSION_DENIED	The requested invoice and template are not associated with the requested user	Accessing resources that don’t belong to your account	invoiceId, templateId

Request validation errors

Issue	Description	Affected fields
INVALID_STRING_LENGTH	Currency code must be 3 characters	/detail/currency_code, /amount/currency_code
INVALID_STRING_MAX_LENGTH	Field exceeds maximum character limit	/detail/note, /items/0/name, /detail/invoice_number
INVALID_PARAMETER_SYNTAX	Invalid format of the dates, phone numbers, or country codes	/detail/invoice_date, /detail/payment_term/due_date
MISSING_REQUIRED_PARAMETER	Required field is missing	/method, /amount/value

Business logic errors

Issue	Description
INVOICE_ALREADY_SENT	The system blocks sending any invoice that has already been sent.
CANT_SEND_INVOICE_WITHOUT_EMAIL	A recipient email address is required before an invoice can be sent.
CANT_CANCEL_INVOICE_IN_DRAFT_STATE	Cannot cancel an invoice that is in draft state.
CANT_PAY_AN_PAID_OR_CANCELED_INVOICE	Cannot record a payment on an invoice that is already paid or canceled.
PAYMENT_AMOUNT_GREATER_THAN_AMOUNT_DUE	Payment amount cannot exceed the total amount due on the invoice.
CANT_REFUND_MORE_THAN_PAYMENT_AMOUNT	Cannot refund more than the amount of recorded payments.
INVOICE_CANNOT_BE_DELETED	Only draft, scheduled, or canceled invoices can be deleted.
INVOICE_NOT_FOUND	Invoice with specified id does not exists.

Field validation limits

Field	Character limit
Invoice number	25
Currency code	3
Country code	2
Email address	3–254
Phone number	1–14 digits
Item name	200
Item description	1000
Invoice note	4000
Terms and conditions	4000
Reference field	120
Logo URL	2000
Website URL	2048