Account recovery
Reset a password with the account email, then sign in again before investigating balance, history, or API keys.
Support
Resolve a CarrierLookup account or API issue
Start with the error code or affected workflow, follow the recommended check, and contact support only when the documented next step does not resolve it.
Reset your password
API request reference
Confirm the X-API-Key header, the phone number you sent, service_type=carrier, response envelope, and published limits.
Payments and balance
Compare credited balance, check counts, payment methods, and the automatic refund rule before opening a payment enquiry.
Error guide
What should you do for each API error?
Use the HTTP status and response code together. Remove secrets before sharing a response with support.
| Status / code | Meaning | Next action |
|---|---|---|
| 401 / 40100 | The API key is missing or invalid. | Send X-API-Key, confirm you copied the active key, and create a replacement in Settings if the original is unavailable. |
| 402 / 40200 | The account does not have enough balance for a carrier lookup. | Check the current price and balance, then complete a top-up before retrying the same request. |
| 429 / 42901 | All five of the account's in-flight request slots are busy, or a multi check is already running on this account. | Wait for the Retry-After seconds, then retry once an in-flight request finishes. The rejected request is not charged. |
| 503 / 50303 | The platform has too many checks in progress right now. | Wait for the Retry-After seconds and resubmit the same request. Nothing was charged. |
| 400 / 40000 | A bulk task file failed the precheck: empty, wrong format, below the minimum, or over the maximum. | Fix the file as the error describes and submit again. The precheck runs before any charge, so this attempt cost nothing. |
| 409 / 40901 | The task has not finished, or its result link is not available yet. | Wait for the task to reach success before fetching the result. Its current state is on the bulk check page. |
| 504 / 50400 | The check did not finish within its timeout (60s single, 300s batch). | Retry the same request; it was not charged. A timed-out batch is refunded in full, so resubmit the whole list. |
| 503 / 50300 | The validation service is temporarily unavailable or in maintenance. | Do not treat the number as having no carrier. Retry later; failed or undetermined lookups do not keep the charge. |
Before contacting support
Include the details that identify the request
Useful context shortens investigation time without requiring passwords or API key values.
- AccountThe email associated with the workspace.
- RequestThe transaction ID, service type, and approximate request time.
- ResponseThe API error code and message, with secrets removed.
Faster support checklist
Most account and API issues can be resolved faster when your message includes account email, service_type, request time and a redacted response body.
Contact: support@carrierlookup.online