Errors

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 token, 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: relevance, rating, rate_asc, rate_desc, experience, completed_events, newest",
  "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 token provided. Identical for a missing, unknown or disabled token.
403	Forbidden	The token is valid but not permitted on this part of the API.
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.

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.