Developer API

Error codes

When a request fails, the API tells you why. Every error links here from its doc_url field, straight to the code it hit.

What an error looks like

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "The 'limit' parameter must be between 1 and 100.",
    "hint": "Nudge detected. Check your parameters.",
    "param": "limit",
    "doc_url": "https://www.kineticist.com/docs/api/errors#invalid_parameter"
  }
}

Go by the HTTP status and code. The message is for people and can change; hint is a bit of pinball flavor and is null when there is none. Which kind of fix each error needs:

Fix the request. Change something and send it again. Repeating it unchanged will fail again.
Check your key. The request was not accepted as coming from a working key.
Wait and retry. The same request will work later. Wait the Retry-After seconds when the response has that header, and back off if it fails again.

Authentication

The request did not carry a key we can accept. Nothing was counted against your limits.

401

missing_api_key

Check your key

The request had no API key. Catalog reads need none; /me endpoints and file downloads need one in the Authorization header.

What to do: Send Authorization: Bearer ki_live_YOUR_KEY. You can create a key in Settings.

Type: authentication_error
Hint: Insert coin to continue.

401

invalid_api_key

Check your key

We got a key, but it does not match any key we have.

What to do: Check for a typo, a cut-off paste, or a stray space or quote. If it still fails, create a new key in Settings.

Type: authentication_error
Hint: Insert coin to continue.

401

revoked_api_key

Check your key

The key was real, but it has been revoked, so it no longer works.

What to do: Create a new key in Settings and swap it in. Retrying the old key will not help.

Type: authentication_error
Hint: This coin has been rejected by the machine.

Rate limits

You sent too many requests. Each of these comes back with a Retry-After header: the number of seconds to wait before the next request.

429

daily_limit_exceeded

Wait and retry

Your key used up its requests for the day. The count resets at midnight UTC.

What to do: Stop until Retry-After has passed. If you need more room, the tier table on the main API page lists the limits.

Type: rate_limit_error
Header: Retry-After
Hint: You're tilting! Step away from the machine and come back tomorrow.

429

minute_limit_exceeded

Wait and retry

Your key sent too many requests in the last minute.

What to do: Wait for Retry-After, then continue at a slower pace. The X-RateLimit-Remaining header on each response shows how much is left.

Type: rate_limit_error
Header: Retry-After
Hint: Slow down — you're nudging too hard.

429

burst_limit_exceeded

Wait and retry

Too many requests landed in the same second.

What to do: Wait for Retry-After (usually one second) and space your requests out instead of firing them all at once.

Type: rate_limit_error
Header: Retry-After
Hint: Whoa, multiball! Ease off the flipper buttons.

Bad requests

Something in the request itself is wrong. Sending it again unchanged will fail the same way.

400

invalid_parameter

Fix the request

A query parameter or value is missing, the wrong shape, or out of range. The param field in the error names the culprit.

What to do: Read message and param, correct that value, and send the request again.

Type: invalid_request_error
Hint: Nudge detected. Check your parameters.

400

offset_too_large

Fix the request

The offset is past 10,000. Lists do not page that deep.

What to do: Narrow the list with filters instead of paging further, then start again from offset 0.

Type: invalid_request_error
Hint: You've reached the end of the playfield. Try narrowing your filters.

Not found

404

not_found

Fix the request

The game, person, manufacturer or other record you asked for is not in the database. A 404 or an empty list always means it really is not there. It never covers for a database hiccup.

What to do: Check the ID or slug. IDs can be sent with or without their prefix, such as gm_. Search the list endpoint if you are not sure of the slug.

Type: not_found_error
Hint: Ball drained. That resource doesn't exist.

Our side

Your request was fine. These are on us, and all of them are worth retrying.

503

temporarily_unavailable

Wait and retry

Our database hiccuped, so we could not answer. This is not the same as the data being missing.

What to do: Wait for Retry-After (a few seconds), then send the same request again. Do not treat it as a 404 or an empty list.

Type: api_error
Header: Retry-After
Hint: Ball search in progress. Try again in a few seconds.

503

download_unavailable

Wait and retry

The file exists, but we could not prepare its download link just now. Only the file download endpoint returns this.

What to do: Try the download again in a few seconds. This response has no Retry-After header, hint or doc_url field, only type, code and message.

Type: api_error

500

server_error

Wait and retry

Something broke on our end that we did not expect. We have been notified.

What to do: Try again in a little while. If the same request keeps failing, tell us which endpoint and when.

Type: api_error
Hint: Machine malfunction. We've been notified.

Back to the API documentation or the API reference.