Connect errors

Authentication errors

A wrong key returns HTTP 401 with a top-level code and message, without the error envelope below. code is invalid_api_key for a key that does not exist, key_revoked for one that was revoked and key_expired for one that has expired. A request with no key returns a plain-text 401 that reads Authentication required, so check the status and Content-Type before parsing. See authentication failures. Check the key and the required authentication header before retrying.

One 401 does use the envelope: CONNECT_AUTH_CONTEXT_MISSING, when the key was accepted but no workspace could be found for it. Email support@complyance.io with meta.requestId.

Onboarding errors

Every other Connect failure contains success: false, error.code, error.message, error.retryable and meta.requestId. error.details is optional, and meta can also include workspaceId. Do not assume the company was not created when a request times out.

Example onboarding failurejson

{
  "success": false,
  "error": {
    "code": "ASP_LINKAGE_NOT_FOUND",
    "message": "No pending ASP linkage was found for this company.",
    "retryable": false
  },
  "meta": {
    "requestId": "01JEXAMPLE0000000000000000",
    "timestamp": "2026-09-22T10:00:00.000Z"
  }
}

Error message wording can vary. Use the returned code and retryability value to decide what to do.

HTTP	Code or condition	Action
`400`	`CONNECT_VALIDATION_ERROR`	Correct missing, malformed or unknown fields
`401`	`invalid_api_key`, `key_revoked` or `key_expired`	Check the API key and required header
`403`	Access denied	Check workspace and operation permissions
`409`	`ASP_LINKAGE_NOT_FOUND`	Check the TIN and `contactPersonEmail` against the UAE prerequisites
`409`	`PEPPOL_PARTICIPANT_UNAVAILABLE`	The company’s Peppol registration could not be confirmed for this TIN and environment. Check that the ASP authorization registered the company with this `tin` in this `platformEnvironment`. If it did, email support@complyance.io with `meta.requestId`
`409`	`CONNECT_COMPANY_ALREADY_EXISTS`	Find the company; reuse its identifiers
`429`	`CONNECT_RATE_LIMIT_EXCEEDED`	Wait for `Retry-After` seconds, also in `error.details.retryAfterSec`, then retry
`502` or `503`	`ONBOARDING_FAILED` or unavailable dependency	Check company listing; retry only when the response permits it
`503`	`CONNECT_RATE_LIMIT_BACKEND_UNAVAILABLE`	Retry with backoff
`504`	`ONBOARDING_TIMEOUT`	Check company listing before retrying creation

For POST /v3/connect/companies/onboarding-jobs, HTTP 200 can include failed rows. Inspect every row’s status, errorCode, errorMessage and nextAction.

Mapping readiness

A successful company response can have readyForInvoicing: false.

Mapping code	Action
`CONNECT_MAPPING_NOT_CONFIGURED`	Select the default mapping for this environment
`CONNECT_MAPPING_INELIGIBLE`	Check that the selected mapping is validated and ready
`CONNECT_MAPPING_CONFLICT`	Review the source’s existing mapping before changing it
`CONNECT_MAPPING_LINK_FAILED`	Check the source and mapping. If it keeps failing, email support@complyance.io with the request identifier

See mappings and payloads.

Count errors

Count failures contain error.code and error.message with meta.requestId and meta.timestamp. They do not define onboarding’s error.retryable field.

Code	Action
`CONNECT_VALIDATION_ERROR`	Remove unsupported filters and correct the parameters
`CONNECT_COMPANY_ID_REQUIRED`	Omit an empty `companyId` or supply a returned identifier
`CONNECT_AUTH_CONTEXT_MISSING`	The key was accepted but no workspace was found for it; email support@complyance.io with `meta.requestId`
`CONNECT_ISV_ACCESS_DENIED`	Verify that the workspace has Connect access
`CONNECT_COMPANY_LOOKUP_FAILED`	Retry the read with backoff
`CONNECT_TRANSACTION_COUNT_LOOKUP_FAILED`	Retry the read with backoff

Country, date and document-type errors are listed in the counts reference.

Request information for support

Email support@complyance.io. Include the endpoint, environment, HTTP status, timestamp, error code and meta.requestId. Remove API keys, signing secrets and unrelated customer data.