Error Handling

Reading data

When a sync reads from an integration and hits an unexpected error, the affected data model is marked FAILED. Subscribe to the SYNC_COMPLETED webhook to be notified when a sync finishes and inspect which data models succeeded — the payload carries status along with per-job counts.

Writing data

Write failures return an error response in this shape:

{
  "error": {
    "code": "An error code (see below)",
    "message": "A description of the error, parsed from the platform error",
    "platform_error": "The full error message returned by the integration platform"
  }
}

Accuracy of error codesMost errors are classified deterministically: first by integration-specific handling, then by HTTP status (429 becomes rate-limit-exceeded, 401/403 become access-denied). Only a write error that none of those recognise falls through to LLM-based mapping, which picks the closest error code and writes the message. Read failures never take that path — they surface as unknown-error.Where the LLM is involved the code may not be exact. platform_error is always the unmodified response from the platform, so prefer it when debugging.

Error codes

Write APIs return 400 with one of the following codes.

Error code	Description
`missing-params`	A field the platform requires was not provided.
`invalid-params`	A field was provided but the platform rejected its value.
`record-already-exists`	A record already exists on the platform with the given field.
`record-not-found`	The referenced record does not exist on the platform.
`operation-denied`	The platform refused the operation.
`platform-denied`	The platform denied the request outright.
`access-denied`	The connection lacks the access required for this operation. Check the data model’s `scope_access` in your sync config.
`token-expired`	The connection’s access token has expired. The customer needs to re-authenticate.
`invalid-refresh-token`	The stored refresh token is no longer valid. The customer needs to re-authenticate.
`already-disconnected`	The connection is already disconnected.
`rate-limit-exceeded`	The underlying platform’s rate limit was hit. Retry with backoff.
`unknown-error`	The platform error could not be mapped to a known code.

Internal errorsAn internal failure returns 500 with the internal-error code. If you receive it, contact support@commenda.io — we monitor internal errors and will investigate.

Connection state and writes

Writes require a healthy connection. If the connection is expired or disconnected, the write is rejected before it reaches the platform, and the customer must re-authenticate. Subscribe to the CONNECTION_CHANGED webhook to catch this as it happens rather than on the next failed write.

General

Use Case Guides

Core Features

Advanced Features

Reading data

Writing data

Error codes

Connection state and writes

​Reading data

​Writing data

​Error codes

​Connection state and writes

Reading data

Writing data

Error codes

Connection state and writes