# Connect errors

Error response formats and recovery actions for Connect requests.

## 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](https://docs.complyance.io/api-reference/authentication/#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.

```json title="Example onboarding failure"
{
  "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](https://docs.complyance.io/partner-platform/isv/companies/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](https://docs.complyance.io/partner-platform/isv/companies/list/); 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](https://docs.complyance.io/partner-platform/isv/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](https://docs.complyance.io/api-reference/connect/invoice-counts/#errors).

## 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.

Source: https://docs.complyance.io/api-reference/connect/errors/