Troubleshooting
Find the symptom below. The error codes themselves are specified in the API reference.
HTTP 400
BAD_REQUEST means the API did not accept the body.
| Cause | Correction |
|---|---|
| The body is not valid JSON. | Correct the JSON. Set Content-Type: application/json. |
The number field is missing. | Add number for one lookup, or numbers for a batch. |
| The number has fewer than 6 digits or more than 11 digits. | Send 6 to 11 digits. Do not send a full card number. |
| The number contains letters or spaces. | Send digits only. |
| The body is larger than 1 KB. | Remove extra fields. |
numbers is empty or has more than 2,000 values. | Send 1 to 2,000 values. See Batch lookups. |
HTTP 401
UNAUTHORIZED means the API did not accept the API key.
| Cause | Correction |
|---|---|
The Authorization header is missing. | Add Authorization: Bearer YOUR_API_KEY. |
The header does not start with Bearer. | Add Bearer and one space before the key. |
| The key has extra spaces or line breaks. | Remove them. |
| The key is revoked or expired. | Check the status on API Keys. Create a new key. |
| The key is not complete. | Copy the full key from your secret store. The dashboard cannot show it again. |
HTTP 403
| Error code | Cause | Correction |
|---|---|---|
FEATURE_NOT_AVAILABLE | The plan does not include the feature. The message names the plan. | Open upgrade_url, or change the plan. |
FORBIDDEN | The key does not have permission for this endpoint. | Create a new key. If the error continues, contact support. |
Batch lookup requires BLAPI-500KPM. The meta object requires BLAPI-150KPM or BLAPI-500KPM. A test-mode organisation can use both.
HTTP 404
A 404 on every request is usually the URL, not the data.
| Cause | Correction |
|---|---|
| The request went to the dashboard host. | Send it to https://api.binlookupapi.com. |
| The path is wrong. | Use /v1/bin or /v1/bins. |
| The method is GET. | Send POST. |
A response with "error": "NOT_FOUND" is different. The URL is correct, and no record matches the BIN. See When a BIN is not found.
HTTP 429
QUOTA_EXCEEDED means the organisation used its daily quota. Requests work again after 00:00 UTC.
| Cause | Explanation |
|---|---|
| You expected a monthly limit. | The limit is per day. BLAPI-30KPM allows 1,000 requests each day. |
| You expected a reset at local midnight. | The reset is at 00:00 UTC. |
| You sent a batch. | Each BIN uses one unit. |
| You use more than one API key. | All keys in the organisation share one quota. |
| The subscription lapsed. | The organisation is on the free tier, with 10 lookups each day. |
Read X-Quota-Limit and X-Quota-Reset. Check Remaining on the home page and the banners on Billing. See Daily quota.
Missing fields
metais missing on the free tier and on BLAPI-30KPM. See The meta object.nullis normal forbrand,category,currency, and the issuer fields. The data source has no value.- Every field in
datais always present. If a field is absent, contact support with the BIN and the request time.
Batch page
The Batch page processes files on BLAPI-500KPM only. On other plans it shows a preview.
- Open Billing.
- Change the plan to BLAPI-500KPM. See Change your plan.
- Open Batch again.
An upgrade is active immediately. File rules are on the Batch CSV page.
CSV upload
| Message | Correction |
|---|---|
Choose a CSV file to upload | Select a file before you start. |
The CSV file is empty | Add at least one BIN. |
The CSV file must be 1 MB or smaller | Split the file. |
CSV contains no data rows | Add a data row. A header alone is not enough. |
CSV has more than 2,000 data rows | Use 2,000 data rows or fewer. |
Daily quota exceeded | Wait until 00:00 UTC, or remove rows. The page shows the required count and the remainder. |
Lookup backend error | Try again later. If it continues, contact support. |
Save the file as CSV in UTF-8, with one BIN in one column.
Payment not shown
The dashboard usually shows the new plan within a few seconds after payment.
- Wait one minute.
- Refresh the Billing page.
- Confirm the organisation. See Switch organisation.
If the free tier is still shown, email support@binlookupapi.com. Include the organisation name, the email address used for payment, and the payment time.
Missing emails
Invitation emails and quota emails come from noreply@binlookupapi.com. Support emails come from support@binlookupapi.com. Add both addresses to your safe list.
For an invitation:
- Check the spam folder.
- Ask an owner to check the address in Pending Invitations.
- Ask the owner to cancel the invitation and send a new one.
An invitation expires after 7 days. See Invite a member.
Quota emails go to owners and billing managers only. Check your role in Settings. See Quota emails.