Connect errors

Authentication errors

HTTP 401 returns a top-level code and message, without the error envelope below. code is invalid_api_key for a key that does not exist and key_revoked for one that was revoked. See the invalid-key response. Check the key and the required authentication header before retrying.

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` or `key_revoked`	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`	Check the existing company and contact support 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; retain the request identifier for support

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`	Correct authentication
`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

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