Failure is part of the contract
Errors
Handle API failures precisely without flattening them into a generic retry.
Status codes
400Validation errorThe request body, path, or query does not match the endpoint schema.
401Authentication errorThe API key is missing, invalid, or revoked.
402Balance errorThe account has insufficient prepaid balance.
404Not foundThe requested BIN, event, visitor, inbox, or resource was not found.
422UnprocessableThe IBAN provider rejected the supplied format.
502Upstream failureA data provider or destination failed to return a usable response.
503UnavailableA required provider integration is not configured.
Error shape
Business errors generally use a compact error string. Schema validation errors currently return the validator’s structured safe-parse result, so clients should branch on HTTP status before reading a specific body shape.
{
"error": "Insufficient balance"
}Retry strategy
- 01
Do not retry 4xx blindly
Fix credentials, balance, validation, or the requested identifier first.
- 02
Back off on 5xx
Use bounded exponential backoff with jitter for transient provider failures.
- 03
Keep operations observable
Record status, endpoint, timing, and your own correlation ID around every call.