DJfindr uses conventional HTTP response codes to indicate the success or failure
of a request.
- Codes in the 2xx range indicate success.
- Codes in the 4xx range indicate a request that failed given the
information provided: a missing key, an unknown record, a parameter out of
range. - Codes in the 5xx range indicate a problem on our side. These are rare.
An error uses the same envelope as a success, with success: false and a
human-readable error. The key set never changes, so a client that parses
responses into a fixed shape does not need a separate path for failures.
On a single-record endpoint:
{ "success": false, "error": "Not found", "data": null }On a list endpoint the list keys are still present, and data is an empty
array:
{
"success": false,
"error": "Unknown sort. Expected one of: platinum_rating, relevance, rating, rate_asc, rate_desc, experience, completed_events, newest, random",
"count": 0,
"remaining": 0,
"cursor": "",
"data": []
}error is written to be read by a person. Where a parameter is at fault it says
which one and what it would accept, as above.
HTTP status code summary
| Code | Response | Meaning |
|---|---|---|
| 200 | OK | Everything worked as expected. |
| 400 | Bad Request | A parameter was unacceptable: an unknown sort, a q over 48 bytes, or too many filter values in one request. |
| 401 | Unauthorized | No valid API key provided. Identical for a missing, unknown, expired, disabled or deleted key. The MCP server is the one exception: it admits requests with no key at all, and returns 401 only for a key that is present and wrong. Its account tools are OAuth only: with no token they answer 401 and a WWW-Authenticate header that says where to sign in (see Connecting an AI Assistant). |
| 403 | Forbidden | The key is valid but lacks the scope this needs, or its account cannot use the API right now. On the Management API, code: "oauth_required" means an API key was sent where an access token is required, and code: "plan_required" means the access token belongs to a DJ whose plan does not include third-party apps (Platinum does). |
| 404 | Not Found | No such record. Also returned for a DJ who exists but is not published. |
| 429 | Too Many Requests | Too many requests too quickly. See Rate Limits. |
| 500 | Server Error | Something went wrong on our end. Rare. |
| 503 | Service Unavailable | A service behind the API was briefly unavailable. Safe to retry. |
A note on 404
A DJ who exists but is not published returns 404, not 403. We do not confirm
that a record exists to a caller who is not allowed to see it, so you cannot use
the API to tell an unpublished DJ apart from one who was never there.
The same applies to a DJ's content. When a DJ hides their mixes, the collection
returns an empty list with a count of 0, byte-identical to a DJ who has no
mixes at all. The setting itself is never exposed.
The Management API adds a few codes of its own and a code to branch on: see
Management API responses.