Errors and what they mean
The error shapes the connector and the app's routes return, with the codes and what to do about each.
There are three families of error: the connector's HTTP refusals, the connector's tool results, and the app routes' detail answers. Each has a fixed shape.
Connector: HTTP refusals
These come back before any tool runs.
| Status | Body | Meaning |
|---|---|---|
| 401 | {"error":"unauthorized","detail":"Provide an AdaptLeads access token as a bearer token. ..."} with a WWW-Authenticate: Bearer realm="adaptleads", resource_metadata="..." header |
No key, a bad key, an expired or revoked key |
| 403 | {"error":"forbidden","detail":"..."} |
The key is real but the account may not use the connector: it is no longer on the approved list, or it is not a member of the organisation |
| 503 | {"error":"unavailable","detail":"The AdaptLeads connector is temporarily disabled."} |
The connector has been switched off |
Refused keys are recorded (a prefix and the time, never the whole key), so repeated guessing is visible to us.
Connector: tool results
A tool that fails still returns an HTTP 200. The error is in the result JSON.
error |
Extra fields | Meaning and what to do |
|---|---|---|
forbidden |
detail |
The key lacks the permission. Create a key with it. Retrying does not help |
rate_limited |
action, retry_after_seconds, limit_scope |
See Rate limits, credits and allowances |
tool_failed |
ref, detail |
Something failed on our side. Quote the ref to support. The cause is never put in the answer |
sector_not_recognised |
sector, suggestions, hint |
Not one of the book's categories. Not proof there are none |
area_too_broad |
area, hint |
The place could not be matched fast enough. Use a postcode area such as M1 or SW |
refused |
detail |
The route behind the tool said no, for example "list not found" |
no_organisation |
The account has no organisation to act on | |
database unavailable |
Try again shortly |
The app's routes
The routes under https://app.adaptleads.co.uk/api/market answer with FastAPI's usual shapes.
| Status | Body | Meaning |
|---|---|---|
| 400 | {"detail":"bad id"} |
A malformed id or body |
| 401 | {"detail":"Could not validate credentials"} |
No sign-in token, an expired one, or a key sent where only a sign-in token works |
| 402 | {"detail":{"detail":"insufficient_credits","credit_balance":0,"needed":1}} |
A reveal needs a credit you do not have |
| 402 | {"detail":{"error":"export_limit_reached","remaining":0,"requested":120,"message":"Monthly export allowance reached..."}} |
The export allowance is used up |
| 403 | {"detail":"..."} |
Not allowed: suspended or closed account, not on the approved list, or not your organisation's |
| 404 | {"detail":"list not found"} |
Not there, or not yours |
| 404 | {"detail":"Not Found"} |
No such route. Skills also answer this if that feature is switched off |
| 413 | {"detail":"That is too long."} |
Body too large |
| 422 | {"detail":[{"type":"missing","loc":["body","password"],"msg":"Field required","input":{...}}]} |
The body did not match. loc names the field |
| 429 | {"detail":"You have used today's 200 questions. They reset at midnight."} |
A daily cap. The message says which |
| 500 | {"detail": ...} generic, with a short reference |
Unhandled error. Nothing internal is shown |
| 502, 503 | {"detail":"..."} |
A helper service did not answer. Try again |
Some limits send 429 with a message, others send 503 when a helper is out of capacity. Read detail.
OAuth errors
The sign-in steps use the OAuth shape:
{"error": "invalid_grant", "error_description": "That refresh token has already been used."}
Codes seen: invalid_request, invalid_target, invalid_scope, invalid_grant, invalid_client_metadata, unsupported_grant_type, temporarily_unavailable.