Management API responses use the same envelope as the Public API, with two additional keys that are present on every response, successful or not.
| Key | Type | Description |
|---|---|---|
code | string | A machine-readable code. Empty ("") on success. On failure, a reason such as onboarding_required, or one of the error codes below. |
fields | object | Validation errors keyed by field name. Empty ({}) when there are none. |
The only response without the envelope is GET /me/calendar/export.ics, which returns the calendar file itself.
{ "success": true, "error": "", "code": "", "fields": {}, "data": { ... } }{
"success": false,
"error": "Some of the request is not valid.",
"code": "invalid",
"fields": { "limit": "Must be a whole number from 1 to 100." },
"data": null
}A list endpoint returns the list envelope for every outcome, including authentication failures and rate limits:
{ "success": false, "error": "Unauthorized", "code": "unauthenticated", "fields": {}, "count": 0, "remaining": 0, "cursor": "", "data": [] }Some endpoints return a list inside the single-record envelope, as part of a larger object. For example, GET /me/mixes returns the mixes together with the plan's limits. The reference shows the response shape of each endpoint.
Error codes
code | Status | Meaning |
|---|---|---|
invalid | 400, 422 | The body, a parameter or a field is not valid. fields names each problem. |
unauthenticated | 401 | The access token is missing, expired or revoked. |
oauth_required | 403 | An API key was sent to an endpoint that requires an access token. |
plan_required | 403 | The person is a DJ whose plan does not include third-party apps. A DJ connects a third-party app on the Platinum plan; until then the token reads only the Public API. |
forbidden | 403 | The token lacks the required scope, or the account cannot perform the action. |
not_found | 404 | The record does not exist or belongs to another person. |
conflict | 409 | The record's state does not allow the action. A more specific code, such as payouts_not_ready or documents_locked, may be returned instead. |
precondition_failed | 412 | The record changed since it was read. See Making changes. |
rate_limited | 429 | Too many requests. Retry after the time in the Retry-After header. |
unavailable | 503 | A service was temporarily unavailable. The request is safe to retry. |
Branch on code, not on error: error is a human-readable message and may change.
Status codes
The Management API uses the status codes listed in Errors, and these in addition:
| Status | Returned when |
|---|---|
| 200 | Starting a conversation or creating the calendar feed found an existing one; nothing new was created. |
| 201 | A record or an action link was created. |
| 400 | The body is not a JSON object, or the Idempotency-Key header is missing where required or malformed. |
| 404 | The record does not exist or belongs to another person. The two cases are indistinguishable. |
| 409 | The record's state does not allow the action. |
| 411 | An upload has no Content-Length header. |
| 412 | The expected_updated_at sent does not match the record. |
| 413 | An upload exceeds 100 MB in one request. |
| 415 | An upload was sent as a form instead of the file itself. |
| 422 | A parameter or field is not valid, or a change was sent a query parameter it does not accept. |
Booking invitations
GET /me/bookings/invitations/{id}is the one exception to the ownership rule. As on DJfindr's invitation page, the invitation id is the key: any signed-in person who holds it can read the invitation.
Pagination
Lists accept limit (1 to 100; the default varies by endpoint) and cursor, and paginate as described in Pagination. Continue until cursor is an empty string.
| Key | Public API | Management API |
|---|---|---|
cursor | Empty on the last page | Empty on the last page |
remaining | The number of records after this page | 1 while another page follows, 0 on the last page |
GET /me/updates is a feed rather than a list: its cursor is never empty and remaining is a count. See Updates.