The Qombo VoP API follows standard HTTP response codes to indicate the success or failure of API requests. This section outlines the possible error responses, their meanings, and how to handle them effectively.

HTTP status codes

The API returns the following status codes:

Status code	Meaning	Description
200 OK	Success	The request was successful, and the response contains the expected data.
400 Bad Request	Client Error	The request is malformed or missing required parameters.
401 Unauthorized	Authentication Error	The API key is missing, invalid, or has insufficient permissions.
403 Forbidden	Authorization Error	The request is valid, but the server refuses to process it (e.g., IP not whitelisted).
404 Not Found	Client Error	The requested resource does not exist.
500 Internal Server Error	Server Error	An unexpected error occurred on the server.

Error response format

When an error occurs, the API returns a JSON response with an error code, message, and additional details (if applicable).

Example Error Response (400 Bad Request)

{
  "error": "The IBAN field is missing.",
  "details": "Ensure that all required fields are included in the request body."
}

Example Error Response (401 Unauthorized)

{
  "error":"Invalid API key.",
  "details": "Ensure you are using a valid API key in the request header."
}

Common Error Scenarios & Fixes

Error Type	Possible Causes	How to Fix
400 Bad Request	Missing or incorrect parameters	Check request body and query parameters.
401 Unauthorized	API key is missing or invalid	Verify the `x-api-key` header and ensure the correct key is used.
403 Forbidden	IP not whitelisted	Ensure your IP is added to the Qombo whitelist.
404 Not Found	Incorrect endpoint or resource ID	Check the endpoint URL and resource identifier.
500 Server Error	API downtime or internal issue	Retry later; if persistent, contact Qombo support.

Response error types

Error Message Code	HTTP Code	Title	Detailer Error
`CLIENT_INVALID`	401	`NOT_REGISTERED_HERE`	The PSP VoP scheme is not reachable at this address.
`CLIENT_INVALID`	401	`NOT_ADHERENT_TO_SCHEME`	The Requesting’s PSP is not adherent to the Scheme
`FORMAT_ERROR`	400	`MISSING_PARTY_IDENTIFICATION`	Fields related to the party identification are missing in the request body.
`FORMAT_ERROR`	400	`INVALID_REQUEST_ID`	The x-request-id header is missing or invalid
`TIMESTAMP_INVALID`	400	`INVALID_TIMESTAMP_HEADER`	The x-request-timestamp header is missing or invalid
`FORMAT_ERROR`	400	`MALFORMED_BODY`	The provided JSON in the request body does not comply with the expected structure.