> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json [expandable] theme={null}
{
    "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](https://paypal.mintlify.app/developer/how-to/api/handling-api-responses#common-paypal-api-error-codes).

| 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            |