Errors and troubleshooting

Connect API v3 uses different public error envelopes for UAE onboarding and document counts. Do not assume fields from one endpoint exist on the other.

Retain meta.requestId from every failure and include it with the endpoint, environment, HTTP status, and timestamp when using the confirmed support path. Never include an API key.

Verification dependency: Engineering must verify unauthenticated and authenticated failures against the deployed gateway. The approved onboarding contract does not yet name every public code for 400, 401, 403, and 429; those names must not be invented. The exact key-management, prerequisite, company-recovery, and support links are also publication dependencies.

UAE onboarding error envelope

POST /v3/connect/companies requires error.code, error.message, and error.retryable. error.details is optional. meta.workspaceId appears only after the workspace is safely resolved.

{
  "success": false,
  "error": {
    "code": "STABLE_PUBLIC_CODE",
    "message": "Human-readable public message.",
    "details": null,
    "retryable": false
  },
  "meta": {
    "requestId": "01JABCDEF1234567890REQUEST",
    "timestamp": "2026-08-15T12:00:00.000Z",
    "workspaceId": "66b9e000c2d3e4f567890000"
  }
}

Error details do not expose internal identifiers, services, or cross-workspace information.

Onboarding remediation matrix

For all rows, use the error.retryable value actually returned. Before retrying a create after a timeout or uncertain dependency failure, check the Company List API to determine whether the company was created.

HTTP	Code or condition	Meaning	Retryable	Caller action
`400`	Validation failure	A required field is missing or invalid, an environment or country is unsupported, an unknown field was sent, or a system ID was supplied.	Follow the response.	Correct the request.
`401`	Missing or invalid API key	Authentication failed.	Follow the response.	Verify the key through the confirmed key-management path.
`403`	Workspace, environment, or operation denied	The key lacks access to the requested scope.	Follow the response.	Verify the key, workspace permission, and environment.
`409`	`ASP_LINKAGE_NOT_FOUND`	The prerequisite is missing for this TIN and environment.	Follow the response.	Complete or verify the approved prerequisite, then check the Company List API before submitting again.
`409`	`PEPPOL_PARTICIPANT_UNAVAILABLE`	The participant cannot be safely verified or linked.	Follow the response.	Verify the prerequisite, check the Company List API, and contact support with `meta.requestId`; no other owner or workspace is disclosed.
`409`	`CONNECT_COMPANY_ALREADY_EXISTS`	The source alias/version or TIN already exists in the workspace.	Follow the response.	Recover `companyId` from the stored response or the Company List API. Do not create another request.
`429`	Workspace rate limit	The workspace exceeded its limit.	Retry after the interval.	Honor `Retry-After`, back off, and confirm the company does not already exist before retrying.
`502` / `503`	`ONBOARDING_FAILED` or dependency unavailable	A required dependency failed.	Follow the response.	Check the Company List API. If the company is absent and the response is retryable, back off before retrying.
`504`	`ONBOARDING_TIMEOUT`	The final outcome may be uncertain.	Follow the response.	Check the Company List API before retrying or contact support with `meta.requestId`.

Retry-After is only for 429 rate limiting. It is not an onboarding polling signal.

Document-count error envelope

GET /v3/connect/invoices/counts defines error.code and error.message. It does not define error.retryable, error.details, or meta.workspaceId.

{
  "success": false,
  "error": {
    "code": "CONNECT_INVALID_DOCUMENT_TYPE",
    "message": "documentType must be sales or purchase."
  },
  "meta": {
    "requestId": "01K1EXAMPLE000000000000000",
    "timestamp": "2026-08-14T12:00:00.000Z"
  }
}

Count retry guidance below is caller guidance, not a response field.

Document-count remediation matrix

HTTP	Code	Meaning	Retry guidance	Caller action
`400`	`CONNECT_VALIDATION_ERROR`	A parameter is missing or malformed, or an unsupported filter was supplied.	Do not retry unchanged.	Correct the request.
`400`	`CONNECT_COMPANY_ID_REQUIRED`	`companyId` was supplied empty.	Do not retry unchanged.	Omit it or provide a returned `companyId`.
`400`	`CONNECT_INVALID_DOCUMENT_TYPE`	The value is not lowercase `sales` or `purchase`.	Do not retry unchanged.	Correct or omit `documentType`.
`400`	`CONNECT_INVALID_ENVIRONMENT`	`X-Environment` is not `sandbox` or `production`.	Do not retry unchanged.	Correct the header; counts does not accept `simulation`.
`400`	`CONNECT_UNSUPPORTED_COUNTRY`	Counts do not support the country.	Do not retry unchanged.	Use `AE`, `SA`, `MY`, `BE`, or `DE`.
`400`	`CONNECT_DATE_RANGE_INCOMPLETE`	Only one date boundary was supplied.	Do not retry unchanged.	Send both `from` and `to`, or neither.
`400`	`CONNECT_INVALID_DATE_RANGE`	`from` is later than `to`.	Do not retry unchanged.	Correct the inclusive range.
`401`	`CONNECT_AUTH_CONTEXT_MISSING`	The key is missing, invalid, or supplied no workspace context.	Retry only after fixing authentication.	Verify the key through the confirmed key-management path.
`403`	`CONNECT_ISV_ACCESS_DENIED`	The workspace cannot use Connect APIs.	Retry only after access changes.	Verify Connect access through the confirmed support path.
`403`	`CONNECT_COMPANY_ACCESS_DENIED`	The company is unknown, cross-workspace, unmanaged, or in another country.	Do not retry unchanged.	Use a `companyId` returned for this workspace and country.
`429`	`CONNECT_RATE_LIMIT_EXCEEDED`	More than 120 requests per minute were sent for the workspace.	Retry after the header interval.	Honor `Retry-After` and back off.
`502`	`CONNECT_COMPANY_LOOKUP_FAILED`	Managed companies could not be resolved.	Retry the read with backoff.	If it persists, contact support with `meta.requestId`.
`502`	`CONNECT_TRANSACTION_COUNT_LOOKUP_FAILED`	Counts could not be retrieved.	Retry the read with backoff.	If it persists, contact support with `meta.requestId`.

Common checks

Confirm the endpoint and HTTP method.
Confirm that X-API-Key is loaded server-side and not logged.
Confirm the environment selector: onboarding body versus count header.
Confirm the UAE prerequisite is ready in the onboarding environment.
Confirm that the company does not already exist before retrying onboarding.
Confirm that a count filter uses returned companyId, not a source, branch, participant, or caller correlation value.
Retain meta.requestId for support.

Next step: Return to the Connect API v3 overview or contact the confirmed support path with meta.requestId if the remediation above does not resolve the error.