Getting started
Errors
The API uses conventional HTTP status codes and a consistent error body. Branch on the status code and the success flag; surface message to your operators for context.
Error shape
Failed requests return success: false and a human-readable message. A data array is occasionally included with validation detail.
Status codes
| Code | Meaning | When you'll see it |
|---|---|---|
| 200 | OK | The request succeeded. |
| 400 | Bad Request | A required parameter or body field is missing or malformed. |
| 401 | Unauthorized | The Authorization header is missing, or a required input was rejected before auth completed. |
| 402 | Payment Required | The key's subscription has expired. Renew it to continue. |
| 403 | Forbidden | The key is invalid, revoked, or lacks the scope for this endpoint. |
| 404 | Not Found | The resource, vendor, or referenced record does not exist. |
| 429 | Too Many Requests | The per-key rate limit was exceeded. Back off and retry. |
| 500 | Server Error | Something failed on our side. Safe to retry with backoff. |
Authentication failures
The auth layer distinguishes several 403conditions by message: a missing or malformed key, an invalid key format or type, a revoked key, and a key without the endpoint's scope. An expired subscription is 402, and rate limiting is 429. Treat the message as informational; branch on the status code.
Error 403 Forbidden
{ "success": false, "message": "This API key has been revoked" }