# Errors, retries, and operational safety

How to design reliable Zild API integrations without duplicating conversations or bypassing guardrails.

Source: https://zild.ai/en-US/docs/api-reference/errors-and-retries

## Status codes



<table class="api-params"><thead><tr><th>Status</th><th>Meaning</th><th>Recommended action</th></tr></thead><tbody><tr><td><code>200</code></td><td>The request was accepted or completed.</td><td>Persist returned IDs if present and continue the workflow.</td></tr><tr><td><code>400</code></td><td>Required payload, metadata, or file data is missing or invalid.</td><td>Fix the request before retrying. For multipart imports, check file field names and required metadata.</td></tr><tr><td><code>401</code> / <code>403</code></td><td>Authentication is missing, invalid, expired, or not allowed for the tenant/resource.</td><td>Refresh the token, rotate the API key, or review role/tenant scope.</td></tr><tr><td><code>404</code></td><td>The requested conversation is not visible or does not exist.</td><td>Confirm the numeric ID and authenticated scope.</td></tr><tr><td><code>429</code> / <code>5xx</code></td><td>The integration should slow down or retry later.</td><td>Use exponential backoff and alert an operator if retries keep failing.</td></tr></tbody></table>



## Retry design

Design callers so a network retry does not create duplicate customer outreach. For proactive conversations, keep your own outbound campaign/item ID and do not retry blindly after an unknown result. For imports, store the source file or transcript identifier and reconcile with Zild conversation records.

## Logging

Log endpoint path, request timestamp, workspace identifier, source record ID, and Zild conversation ID. Do not log API keys, bearer tokens, raw customer secrets, or full transcripts unless your retention policy allows it.

## Human review guardrails

When a request can trigger customer-visible action, prefer configured templates, queues, and users over ad hoc automation. If the source system lacks enough context for an AI decision, create or route the conversation with the right metadata and let the platform escalate.