Errors and retries
Handle validation, authentication, rate-limit, transient, and terminal failures predictably, with retry guidance for each class of Ultrafield error.
Classify an error before deciding to retry it.
| Class | Typical response |
|---|---|
| Validation | Fix the request; retrying the same input will not help |
| Authentication or authorization | Correct credentials or access; do not loop |
| Rate or capacity | Back off according to response guidance and add jitter |
| Transient service or network failure | Retry with bounded exponential backoff |
| Unsupported or invalid audio | Inspect encoding, container, duration, or corruption |
| Terminal processing failure | Record the failure and route it for application-specific handling |
Retry safely
- Set connect and overall request timeouts appropriate to batch or streaming work.
- Use bounded exponential backoff with jitter.
- Cap total attempts and surface exhausted work to an operator or dead-letter queue.
- Preserve a stable application request identifier where supported.
- Reconcile asynchronous job state after ambiguous network failures before submitting duplicate work.
Log useful context
Record your request identifier, the Ultrafield job or request identifier, model route, processing stages, error class, and attempt number. Never log API keys or sensitive raw audio by default.
Webhooks
Receive job completion and processing events asynchronously. Verify signatures, handle retries and replays, and keep your endpoint safe under load.
Security and data handling
Design Ultrafield integrations around least privilege, deliberate retention, and safe handling of audio and transcript data.