API Documentation
Errors
How the CoverageMap APIs report errors, the common error messages and when to retry.
When a request cannot be completed the API responds with an error status and explains why in messages.errors. Rejected requests are never billed.
Error format
Errors use the normal response envelope. Validation reports every problem it finds at once, so fix them all before trying again:
400 response
{
"status": 400,
"messages": {
"errors": [
"datasets must contain at least one of: fcc-coverage, speed-tests, summary",
"locations must contain at least one location"
]
},
"data": null
}Common errors
These errors can come from any CoverageMap API.
| Message | Status | What to do |
|---|---|---|
Missing API key | 400 | Send your key in the Authorization header. |
Invalid API key | 400 | Check the key was copied in full and has not been deleted. |
Subscription is not active | 400 | Renew or upgrade the subscription in the dashboard. |
API key is not valid for this product | 400 | Use a key from a subscription to the API you are calling. |
API key is not valid for this domain | 400 | Send a Referer from one of the key’s associated domains, or use a different key. |
API key has exceeded its usage limit | 400 | The subscription has used its allowance. Upgrade, or wait for the next period. |
API key would exceed its usage limit | 400 | The request costs more units than remain. Send a smaller request or upgrade. |
No content type found in request headers | 400 | Add Content-Type: application/json to requests with a body. |
Unsupported content type: … | 400 | Send the body as application/json. |
Request body must be valid JSON | 400 | The body is empty or is not valid JSON. |
Invalid endpoint | 400 | Check the path and HTTP method. |
An unexpected error occurred | 500 | Retry with backoff. Contact us if it keeps happening. |
Errors specific to one API are listed on its endpoint pages:
- CoverageMap API: Coverage lookup, List countries, List providers
Retries
- 400: do not retry the same request. Fix what the messages describe first.
- 500, 503 and network errors: retry with exponential backoff, for example after 1, 2, 4 and 8 seconds, and give up after a few attempts.
Retries and billing
A retried request is billed like any other request once it succeeds, so avoid retrying requests that already returned a 200.