Errors
What each error means, and what happens to your credit.
FILTER distinguishes a malformed REQUEST from a malformed PHONE NUMBER — they are handled differently, and the difference is worth reading closely.
A malformed request
Missing the phone field, invalid JSON, no check type enabled in your account Settings, or more than 1,000 numbers in a bulk batch — these return 400 INVALID_REQUEST and charge nothing. Nothing was queryable, so nothing was attempted.
A malformed phone number
A well-formed request whose phone value isn't a valid number is different: it returns 200, not 400, with status ABSENT — and it does charge a credit. This is deliberate, documented behaviour, not a bug: a bad number from your own input source is still a real lookup attempt from our side, the same way a genuinely disconnected number would be.
A network or infrastructure failure
If the upstream network is unreachable, or the request times out on our side, you get status UNDETERMINED and the credit is refunded automatically — this is the one case where a credit comes back. Retrying is safe and expected.
Summary
| Situation | HTTP | status | Credit |
|---|---|---|---|
| Malformed request body | 400 | — | Not charged |
| Malformed phone number | 200 | ABSENT | Charged |
| Valid lookup, any outcome | 200 | CONNECTED / ABSENT | Charged |
| Network/infra failure or timeout | 200 | UNDETERMINED | Refunded |