Troubleshooting Pleo API errors

The request is invalid or fails validation.

• Read the response body to identify missing fields or invalid values.
• Compare your request with the endpoint documentation. Check required fields, request structure, date formats and allowed values.
• Correct the identified issue and retry the request.

The request could not be authenticated.

• Match the credential to the API and environment. Check the request host against the developer documentation. Do not mix New API and Legacy API credentials, or staging and production credentials.
• Check the authorisation header (`Authorization`). New API keys use Basic authentication, with the key as the username and an empty password. OAuth access tokens use Bearer authentication. Follow the Legacy API documentation for legacy tokens. Remove accidental spaces or line breaks from credentials.
• Check the credential’s status. Confirm it has not expired or been revoked. For OAuth, use the access token—not the refresh token—and check that the token refresh flow is working.

The request was authenticated, but access is not allowed.

• Check scopes. Compare your credential’s assigned scopes with those required by the endpoint. If you cannot view them, ask the person who manages the credential to confirm them.
• Check the company and environment. The credential must match the company or entity whose data you are requesting and the environment you are calling.
• Check endpoint availability. Confirm in the developer documentation that the endpoint supports your authentication method and use case.

If these match but access is still denied, contact Support to confirm the company’s API access. Mention whether the same credential works on other endpoints.

The requested endpoint or resource could not be found.

• Compare the base URL, API version and endpoint path with the developer documentation.
• Confirm that the resource ID identifies the resource you intended to request.
• Check that the resource belongs to the company and environment associated with the credential. Do not mix staging and production IDs.

A resource may return 404 even if it exists in Pleo when it belongs to a different company or environment.

The request conflicts with an existing operation or state.

• Read the error response and check whether the same operation was already submitted. Review the previous response or resulting operation before sending it again.
• Follow the endpoint’s conflict and idempotency guidance in the developer documentation.

Your integration is sending requests too frequently.

• Check response headers for retry or rate-limit guidance.
• Reduce request frequency and avoid immediate retries in a tight loop.
• Use exponential backoff, following the endpoint’s retry guidance.

If this continues at low request volume, include your request frequency and retry behaviour when contacting Support.

A server-side error occurred. Collect the error response and request details listed under “Still need help?” and contact Support. Mention whether it happened once or occurs repeatedly.

If webhook events are not reaching or being processed by your integration:

• Check reachability. Your receiving endpoint must be publicly accessible over HTTPS and must not block requests from Pleo.
• Check delivery logs. Look for the delivery attempt, response status and response time. Return a 2xx response promptly, following the webhook documentation’s requirements.
• Check signature verification. Use the request body in the form required by the webhook documentation, including the raw body where specified.
• Handle duplicate deliveries safely. Deduplicate using the event or webhook identifier specified in the documentation.

After making a change, check a subsequent delivery. If it still fails, include the subscription ID, event or webhook ID, delivery timestamp, endpoint response status and sanitised logs when contacting Support.