Error handling | MediaKind Docs

Error handling

The MK.IO APIs return the same error body for every failure. Once your client handles that one shape, the rest of error handling is consistent across the platform: inspect the HTTP status, branch on the machine-readable code, log the human-readable detail, and keep the request reference for follow-up.

The standard error body

When an operation fails, the API returns a JSON object with this shape:

{

"error": {

"code": "<error_code>",

"detail": "<error_message>",

"extraDetail": {}

},

"status": 400,

"ref": "<request_reference>"

}

Each field has a distinct job:

Field	Use it for
`error.code`	Programmatic branching in your application.
`error.detail`	Logs, dashboards, and operator-facing messages.
`error.extraDetail`	Any additional context the API includes.
`status`	The HTTP status code, repeated in the body.
`ref`	Support follow-up and request tracing.

If you keep only one field beyond the status line, keep ref. It is the quickest way to identify a failing request afterwards.

Status codes across the platform

The exact response set varies by endpoint, but these codes appear throughout the APIs.

Success responses:

Code	Meaning
`200`	The request succeeded and returned a body.
`201`	The resource was created.
`202`	The request was accepted and continues asynchronously.
`204`	The request succeeded with no response body.

Client-side problems:

Code	Meaning	What to do next
`400`	Bad Request	Recheck the path, query parameters, and body format.
`401`	Unauthorized	Recheck the bearer token and `Authorization` header.
`403`	Forbidden	Recheck organization, project, and operation access for the token’s user.
`404`	Not Found	Recheck names and path parameters, especially project-scoped names.
`409`	Conflict	Recheck the resource state, or whether the operation conflicts with an existing reference.
`429`	Too Many Requests	Back off and retry later. See Rate limits.

Server-side problems:

Code	Meaning	What to do next
`500`	Internal Server Error	Retry carefully and keep the `ref` value.
`503`	Service Unavailable	Treat it as temporary and keep the `ref` value if it persists.

A handling order that works

When a request fails:

Record the HTTP status code.
Parse error.code and error.detail.
Record ref.
Decide whether to fix the request, retry it, or surface it to an operator.

As a guide to that decision:

400, 401, 403, and many 404 responses mean the request needs correcting.
409 usually means the operation is valid, but the target resource is not in the right state yet, or is still referenced elsewhere.
429, 500, and 503 are the cases where careful retry logic pays off.

See the status and body together

When you debug from the command line, print the transport status alongside the body so a log line captures both:

curl -sS \

-H "Authorization: Bearer <YOUR_TOKEN>" \

-H "Accept: application/json" \

-w "\nHTTP Status: %{http_code}\n" \

"https://app.mk.io/api/v1/projects/<PROJECT_NAME>/media/assets/nonexistent"