Troubleshooting

Each section follows the same shape: symptom, likely cause, fix, and where to read the exact contract.

Authentication or Team Selection

Symptom: requests fail with 401 or 403.

Likely cause: wrong API base URL, wrong credential type, a disabled or expired key, missing team access, or a partner-scoped route called with a team selector (or the reverse).

Fix: verify the public API base URL, then credential type, key status, and team access. Send only the team selector the route documents, and never fall back to another accessible team after a write failure.

See: Team Context, Read the selected team — GET /team, and Error Contract.

Embedded Session

Symptom: the embedded UI fails to authenticate, or stops working after a few minutes.

Likely cause: the browser received a partner API key instead of a session bearer token, the session passed expiresAt, or the issued team does not match the team the iframe shows. Unknown embedded users fail session creation unless auto-provisioning is enabled; inactive users need account repair.

Fix: sessions must come from your backend and be refreshed before expiresAt. Keep the session and iframe on the same team, and provision or repair the embedded user.

See: Issue Sessions and Issue an embedded session — POST /partner/embed-sessions.

Connection Creation

Symptom: creating or connecting a source fails, or an OAuth callback does not complete.

Likely cause: an appId that does not exactly match GET /apps, callback parameters altered in transit, or the OAuth flow completed under a different team than the one that initiated the signed state.

Fix: take the appId verbatim from GET /apps, return callback params unchanged, and complete the flow under the team that started it. If a provider response left the outcome uncertain, read current connection and sync state before acting again.

See: Connections, List apps — GET /apps, Create a connection — POST /connections, and Connect an app — POST /connections/connect.

Team Issues

Symptom: GET /teams/issues returns 400 or an initial 503.

Likely cause: for 400, an invalid team UUID, unknown issue code, stale cursor, or another strict query parameter. For 503, a team in scope whose first issue snapshot is not yet materialized.

Fix: for 400, validate UUIDs, codes, and cursors against the generated contract. For 503, retry after retryAfterSeconds, or scope teamIds to exclude the teams listed in pendingTeamIds. When consuming events, compare snapshot versions and replace local issue state rather than merging event codes.

See: Portfolio health, Read team issues — GET /teams/issues, and Error Contract.

Webhook Delivery

Symptom: deliveries fail, stop arriving, or are rejected by your receiver.

Likely cause: signature verification against a parsed (not raw) body, a receiver that returns non-2xx before durable processing, or a subscription disabled by 410 or by delete.

Fix: the delivery endpoints show attempts, response status, a sanitized excerpt, and the next attempt time; start there. Verify the signature over the raw body, and return 2xx only once processing is durable. Once the receiver is fixed, replay the existing delivery instead of creating a second subscription.

See: Webhooks, Inspect deliveries — GET /webhook-deliveries, and Replay a delivery — POST /webhook-deliveries/{id}/replay.

Batch Imports

Symptom: batch submissions are rejected, or accepted batches do not produce the expected data.

Likely cause: wrong team context, unstable uniqueRef values that create duplicates or update the wrong record, or item payloads that fail the operation's schema or business rules.

Fix: verify x-api-key and x-team-id, and keep uniqueRef stable per source record. A batch is not all-or-nothing: process the response item by item, since each outcome appears in data and failures arrive as structured issues. For risky batches, validate first with the dryRun parameter where the operation declares it.

See: Batch imports, Contact batch — POST /contacts/batch, Listing batch — POST /listings/batch, Reservation batch — POST /reservations/batch, Transaction batch — POST /transactions/batch, Bank-account batch — POST /bank-accounts/batch, and Bank-record batch — POST /bank-records/batch.

Escalation

If the structured error and generated operation do not explain the failure, provide support with timestamp, route, team ID, correlation ID, and redacted request shape.