Error Handling

Who this is for: every integrator. When to use it: when building robust clients. What happens next: you'll handle failures predictably and know when to retry.

Zamplia uses conventional HTTP status codes and returns a structured body on errors so you can react programmatically.

Status codes

Code	Meaning	What to do
200	Success	Process the response
400	Bad request — missing/invalid parameters	Fix the request; do not retry unchanged
401	Unauthorized — missing/invalid credentials	Check your auth header
404	Not found — wrong endpoint or environment	Verify the path and base URL
500	Server error on Zamplia's side	Retry with backoff; if it persists, contact Support

Reading an error

Error responses include a structured payload describing what went wrong. Log the full body (minus secrets) and surface the message to your operators.

Example error shape

{
  "status": 400,
  "message": "Required parameter is missing or invalid."
}

Retry strategy

• Do not retry 400/401/404 without changing the request — they are deterministic.
• Do retry 500 and network timeouts with exponential backoff and jitter (e.g. 1s, 2s, 4s, capped).
• Make write operations idempotent where possible so a retry can't double-create.

Common pitfalls

• Wrong environment: production credentials against a sandbox host (or vice versa) returns 401. See Environments.
• Missing auth header: ZAMP-KEY (Supply) or Authorization: Bearer (Demand).
• Sending traffic against a full quota — handled at redirect, not as an error. See Redirect Handling.

tip

Reproduce and debug failures safely in the Sandbox before they reach production.