API Response Codes and Error Handling
Most Peleza endpoints return a shared JSON envelope. Use response_code, message, and request_id together with the HTTP status when handling errors.
Success envelope
Successful calls typically look like:
- success: true
- response_code: 200 (or 202 for accepted async jobs)
- message: human-readable status
- data: endpoint payload
- request_id: UUID for support and audit
Common HTTP statuses
These statuses appear across the APIs:
- 200 — Success (or cached manual-verification hit)
- 202 — Accepted for async processing (manual verification / some digital-credentials flows)
- 400 — Validation error (missing or invalid fields such as id_number)
- 401 — Invalid or missing Bearer token
- 403 — Forbidden / service not enabled for your account
- 404 — Resource not found
- 408 — Request timed out
- 429 — Rate limited
- 503 — Service temporarily unavailable
Notes
Some middleware responses (especially 401, 403, 503) may omit the full envelope or use a different shape. Prefer HTTP status plus any message fields present. Always log request_id when returned.