This page explains how Qombo classifies API errors and how to fix them.

API error format

Qombo API endpoints return errors in this format:

{
  "error": "Human-readable message",
  "code": "ERROR_CODE",
  "details": ["Optional field-level details"]
}

HTTP status codes

HTTP status	What it means	What to do
`400 Bad Request`	The request format or one of the provided values is invalid.	Fix the request body, query string, file, or identifier and retry.
`401 Unauthorized`	Authentication failed.	Check your API key, client certificate setup, and any IP restrictions.
`403 Forbidden`	The request is valid, but the action is not allowed for your organisation or configuration.	Check enabled modules, feature access, and operation-specific permissions.
`404 Not Found`	The requested resource does not exist.	Verify the identifier you sent and whether the target resource still exists.
`409 Conflict`	The request conflicts with existing data.	Update the request to avoid duplicates or already-existing resources.
`429 Too Many Requests`	You sent too many requests in a short time.	Wait and retry later.
`500 Internal Server Error`	Qombo could not complete the request because of an internal issue.	Retry later. If the problem persists, contact Qombo support with request context.

API error codes

Code	HTTP status	Meaning	What to do
`INVALID_DATA`	`400`	A request field, query parameter, cursor, identifier, or other client-provided value is invalid.	Review the request format and use `details` when present to correct the payload.
`AUTHENTICATION_FAILED`	`401`	Authentication could not be completed.	Check your API key, mTLS certificate, request origin IP, and authentication headers.
`MODULE_NOT_ACTIVATED`	`403`	Your organisation does not have access to the requested module.	Contact Qombo support to enable the module.
`RATE_LIMIT_EXCEEDED`	`429`	You exceeded a request-rate protection rule.	Wait before retrying the same request.
`TECHNICAL_ERROR`	`500`	Qombo encountered an internal technical issue while processing the request.	Retry later. If repeated, contact support.
`VOP_INVALID_EXPOSE_OPTION`	`403`	Your organisation is trying to use the cloud expose option but it's not activated.	Use the correct responding setup for your organisation.
`VOP_INVALID_FILE`	`400`	The uploaded file is missing, has the wrong type, cannot be parsed, or contains invalid data.	Upload a valid CSV file and fix any parsing or row-format issues shown in `details`.
`SHARING_INVALID_REPORT_ID`	`400`	The report ID in the request path is invalid.	Send a valid numeric report ID.
`SHARING_INVALID_ALERT_ID`	`400`	The alert ID in the request path is invalid.	Send a valid numeric alert ID.
`SHARING_REPORT_CONTEXT_ALREADY_SET`	`400`	The report context cannot be updated because source or channel information is already set.	Do not retry the same update. Treat the report context as already locked.
`SHARING_REPORT_NOT_FOUND`	`404`	The requested report does not exist.	Verify the report ID before retrying.
`SHARING_ALERT_NOT_FOUND`	`404`	The requested alert does not exist.	Verify the alert ID before retrying.
`SHARING_REPORT_QUALIFY_FORBIDDEN`	`403`	Your organisation is not allowed to qualify this report.	Check that you are acting on a report your organisation is allowed to qualify.
`SHARING_REPORT_QUALIFY_DELETED`	`403`	The report has already been deleted and cannot be qualified.	Stop retrying, the report cannot be qualified.
`SHARING_REPORT_DELETE_FORBIDDEN`	`403`	Your organisation is not allowed to delete this report.	Check that your organisation owns the report before retrying.
`SHARING_REPORT_ALREADY_DELETED`	`403`	The report is already deleted.	Treat the delete as already completed and refresh local state.
`SHARING_REPORT_UPDATE_FORBIDDEN`	`403`	Your organisation is not allowed to update this report.	Check permissions and report ownership before retrying.
`SHARING_REPORT_UPDATE_DELETED`	`403`	The report is already deleted and cannot be updated.	Stop retrying, the report cannot be updated.
`SHARING_DUPLICATES_IBAN`	`409`	The request contains the same IBAN more than once.	Remove duplicates from the request and retry.
`SHARING_IBAN_EXISTING_YOUR_LISTS`	`409`	At least one IBAN already exists in one of your organisation’s lists.	Remove existing entries from the request.
`SHARING_IBAN_EXISTING_ANOTHER_LIST`	`409`	At least one IBAN is already linked to another organisation’s list.	Do not retry unchanged. Contact Qombo support if ownership looks incorrect.
`SHARING_IBAN_NOT_FOUND`	`404`	At least one IBAN was not found in the expected organisation list.	Refresh your local list and retry with the correct IBAN set.

EPC error classification

For EPC scheme-facing VoP exchanges, the response format follows EPC conventions.

Code	HTTP status	Title	Meaning	What to do
`FORMAT_ERROR`	`400`	`MALFORMED_BODY`	The JSON body does not match the expected EPC request structure.	Rebuild the request body according to the EPC schema.
`FORMAT_ERROR`	`400`	`INVALID_REQUEST_ID`	The `x-request-id` header is missing or invalid.	Send a valid `x-request-id`.
`TIMESTAMP_INVALID`	`400`	`INVALID_TIMESTAMP_HEADER`	The `x-request-timestamp` header is missing or invalid.	Send a valid timestamp header in the expected format.
`FORMAT_ERROR`	`400`	`MISSING_PARTY_IDENTIFICATION`	Required party-identification information is missing.	Add the missing payee identification fields.
`CLIENT_INVALID`	`401`	`NOT_REGISTERED_HERE`	The requesting PSP is not recognised for this route or environment.	Verify that you are calling the correct target and environment.
`CLIENT_INVALID`	`401`	`NOT_ADHERENT_TO_SCHEME`	The requesting PSP is not accepted as a valid scheme participant.	Check your scheme onboarding and participant configuration.

Common examples

Example: invalid request body

{
  "error": "Invalid data",
  "code": "INVALID_DATA",
  "details": ["party.companyids.0.companyid.fr_siret: invalid fr_siret format"]
}

Meaning: the request is structurally valid JSON, but one input value is invalid.

Action: fix the field listed in details and resend the request.

Example: authentication failure

{
  "error": "Invalid API key",
  "code": "AUTHENTICATION_FAILED"
}

Meaning: Qombo could not authenticate the caller.

Action: verify your API key, environment, and authentication setup.

Example: sharing conflict

{
  "error": "The request contains duplicate IBANs",
  "code": "SHARING_DUPLICATES_IBAN"
}

Meaning: the request conflicts with itself before Qombo can process it.

Action: remove duplicate IBANs and retry.