Zintara API errors: classify authentication, validation and uncertain writes

Define the decision

A valid network response can still be an application failure. The reviewed handlers use ok/error responses for JSON operations, while an export can return CSV. Parse according to status and content type rather than forcing every body through the same schema.

Work through the procedure

1. Record method, route, status and a redacted response.
2. For 401, check the credential; for 403, check route scope and authorization.
3. For 400, repair input; for 409 on lead creation, reconcile the existing address.
4. For a timeout or 5xx on a write, investigate whether the action already occurred before retrying.

Worked example

The following is a synthetic example for this procedure, not a customer result or performance benchmark.

POST /api/leads with an existing email → 409
Desired recovery: locate the existing lead and apply the approved merge policy
Wrong recovery: repeat the same create request indefinitely

Read the result

The error class helps identify the owner. A key restricted to leads cannot be used as an administrator session, and a missing route is not fixed by granting more scopes.

Check before moving on

1. Keep personally identifying response data out of shared logs.
2. Preserve the original attempt ID in your own consumer records.

Limits and next action

Only confirm success after validating the expected response and resulting state. A generic HTTP client resolving its promise is not enough.

Source: Zintara implementation and product context