Skip to main content
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 codeError nameMessageDetails
400INVALID_REQUESTInvalid requestOne or more validation errors have occurred.
401AUTHENTICATION_FAILUREAuthorization error occurredAuthorization error occurred. Check your credentials.
404RESOURCE_NOT_FOUNDResource not foundThe resource requested is not found in the system.
422UNPROCESSABLE_ENTITYInvoicing business errorA detailed error message is passed in the message field.
429RATE_LIMIT_REACHEDToo many requests and user is blocked due to rate limitingThe rate limit for the user, application, or token exceeds a predefined value.
500INTERNAL_SERVER_ERRORInternal service errorResend the request at another time.

​
Authorization errors

HTTP codeIssueMessageCommon causeAffected fields
403NOT_AUTHORIZEDAuthorization failed due to insufficient permissionsInvalid access token or account permissions
  • invoiceId
  • templateId
403PERMISSION_DENIEDThe requested invoice and template are not associated with the requested userAccessing resources that don’t belong to your account
  • invoiceId
  • templateId

​
Request validation errors

IssueDescriptionAffected fields
INVALID_STRING_LENGTHCurrency code must be 3 characters
  • /detail/currency_code
  • /amount/currency_code
INVALID_STRING_MAX_LENGTHField exceeds maximum character limit
  • /detail/note
  • /items/0/name
  • /detail/invoice_number
INVALID_PARAMETER_SYNTAXInvalid format of the dates, phone numbers, or country codes
  • /detail/invoice_date
  • /detail/payment_term/due_date
MISSING_REQUIRED_PARAMETERRequired field is missing
  • /method
  • /amount/value

​
Business logic errors

IssueDescription
INVOICE_ALREADY_SENTThe system blocks sending any invoice that has already been sent.
CANT_SEND_INVOICE_WITHOUT_EMAILA recipient email address is required before an invoice can be sent.
CANT_CANCEL_INVOICE_IN_DRAFT_STATECannot cancel an invoice that is in draft state.
CANT_PAY_AN_PAID_OR_CANCELED_INVOICECannot record a payment on an invoice that is already paid or canceled.
PAYMENT_AMOUNT_GREATER_THAN_AMOUNT_DUEPayment amount cannot exceed the total amount due on the invoice.
CANT_REFUND_MORE_THAN_PAYMENT_AMOUNTCannot refund more than the amount of recorded payments.
INVOICE_CANNOT_BE_DELETEDOnly draft, scheduled, or canceled invoices can be deleted.
INVOICE_NOT_FOUNDInvoice with specified id does not exists.

​
Field validation limits

FieldCharacter limit
Invoice number25
Currency code3
Country code2
Email address3–254
Phone number1–14 digits
Item name200
Item description1000
Invoice note4000
Terms and conditions4000
Reference field120
Logo URL2000
Website URL2048
⌘I