Errors and troubleshooting

Common status codes

Use both the HTTP status and structured error body when deciding what to do next.

• 400 — the request is invalid; fix it before retrying.
• 401 — the key is missing, invalid, expired, revoked, or malformed.
• 403 — the key is valid but lacks the required scope or workspace access.
• 404 — the endpoint or authorized resource was not found.
• 429 — the caller has exceeded a limit; retry with bounded backoff.
• 500 — Patvero could not complete the request; retain the request ID and retry only when safe.

Retry safely

Do not retry every error automatically.

• Never retry 400 or 403 without changing the request or authorization.
• Refresh configuration after 401 instead of logging the complete key.
• Use exponential backoff and jitter for 429 and temporary server errors.
• Set timeouts and cap total retry duration.
• Use idempotency controls on write APIs when the specific endpoint documents them.

What to capture

Capture the timestamp, HTTP method, path, response status, error code, request ID, correlation ID, and your integration's own trace ID.