API error codes and responses

All endpoints follow the same pattern, and each error response includes a descriptive message in either JSON or XML format depending on the request. Here are the common error codes you may encounter and how to interpret them.

Successful response codes

200 OK — The request was successful and returned data as expected.
204 No Content — The request was successful, but there was no content to return (for example when querying a list with no matching results).

Client error codes (4xx)

These indicate issues with the request from your application, and typically mean that the request parameters, authentication, or resource identifiers are incorrect.

400 Invalid Request — The request could not be processed due to invalid parameters or malformed syntax. Check the request payload and structure.
401 Unauthorized — The API key was missing or invalid. All requests require a valid key in the Authorization header.
403 Forbidden — The API key used does not have permission for the requested operation. You may need to check role scopes or partner privileges.
404 Not Found — The requested resource (such as a specific endpoint, account, or identifier) doesn’t exist. This often results from an incorrect URL path or invalid query parameter.
409 Conflict — A conflict occurred, usually due to duplicate resource creation or conflicting state. For example, sending an already existing unique identifier.
422 Unprocessable Entity — The format or content of the data was syntactically correct but semantically invalid. This typically means required fields are missing or values don’t meet schema/Peppol validation rules.
429 Too Many Requests — You have reached a rate limit. Slow down or add retry logic with exponential backoff.

Server error codes (5xx)

These indicate an issue on the Qvalia side. In most circumstances, you should retry the call and, if it persists, contact Qvalia support.

500 Internal Error — The server encountered an unexpected condition. This is not due to client errors; contact support if the issue persists.

Interpreting error responses

Along with the HTTP status code, Qvalia returns a descriptive message in the response body. If you request XML, the response will be in XML format; if you request JSON (default), the response will be in JSON.

Best practices

Always check the HTTP status code first. If it’s in the 4xx range, correct the request; if it’s in the 5xx range, consider retrying after a short delay.
Include meaningful error handling and logging in your integration to capture both the HTTP status and the error message.
For authentication errors, verify that your API key is present, correct, and has the right permissions.
Handle rate limiting (429) gracefully by implementing retry with delays.
Use the transaction log in the Qvalia portal to correlate API errors with processed messages and metadata for operational diagnostics.