Documentation

Errors and limits

What the API tells you when a request does not succeed, what each status code actually means here, and what to quote when you need us to look into one.

The error shape

API errors come back in the OpenAI error envelope, so an SDK's own error handling already understands them. The HTTP status carries the meaning; the message explains it in words.

{
  "error": {
    "message": "Authentication Error, No api key passed in.",
    "type": "auth_error",
    "param": "None",
    "code": "401"
  }
}

Status codes

HTTP status codes the API returns, and what to do about each
Status	What it means	What to do
`400`	The request body was not acceptable — a malformed payload, or a parameter the chosen model rejects. An exhausted budget is also reported here.	Read the message. If it names a budget, add credit; otherwise fix the field it names.
`401`	No key, an unknown key, or a key that has been revoked.	Check the Authorization header is present and spelled Bearer. If the key was revoked, issue a new one from the portal.
`404`	The model id does not exist in the catalogue.	Check the spelling against the Models page. Ids are case-sensitive, and a model may have been withdrawn.
`429`	More requests than the capacity available right now, either yours or the upstream provider's.	Back off and retry with exponential jitter. Persistent 429s on ordinary traffic are worth telling us about.
`500, 502, 503, 504`	Something failed on our side or at the upstream provider.	Retry — these are usually transient. If they persist, contact support with the details below.

Budget errors are refusals, not failures

When a balance or a group limit is exhausted, the gateway refuses the request rather than running it and billing afterwards. Adding credit restores service at once; there is nothing to re-enable. See Billing and credit.

Reference codes in the portal

When something goes wrong inside the portal — not the API — you are shown a short reference code in place of the underlying technical detail, for example Something went wrong. Quote reference K7M2PQX4 if you contact support.

The code is eight characters and deliberately avoids letters and digits that look alike, so it survives being read out over a phone.
It identifies that exact failure in our logs. Quoting it turns "the top up page broke" into a single line we can find in seconds.
It is not secret and says nothing about your account — it is safe to paste into an email.

API errors do not carry one

A reference code comes from the portal. For a failing API call, send the details in the next section instead.

What to send us about a failing call

The more of this you include, the faster we can find it:

The time it happened, with the time zone.
The model id you asked for, and the HTTP status you got back.
The full error message and type.
The label of the key you used — never the key itself. If you have already pasted a key into an email or a ticket, revoke it and issue a new one.
The id from a successful response, if the problem is with an answer rather than an error.

Send it to kakehashi@classmethod.my.

Limits

Request rate

Kakehashi does not publish a fixed per-key request or token rate. Capacity is shared, and the practical ceiling is whatever the upstream provider allows for the model you are calling — which is why a burst can meet a 429 even when your balance is healthy.

Build retry-with-backoff into any production integration. If you need guaranteed throughput for a launch or a batch job, talk to your account manager beforehand rather than discovering the ceiling in production.

Spending limits

Three separate ceilings can stop a request, and the message names which one did: the prepaid balance, a group limit and a key budget. Only the first is about money you have; the other two are caps somebody chose. See Organizations and groups.

Long requests and timeouts

A very long generation can exceed the gateway's request timeout and be cut off. Streaming is the usual answer: tokens arrive as they are produced, so the connection is never idle waiting for a complete reply.

The first request after a quiet period can also be slower than the rest while capacity comes back up. Set client timeouts with that in mind, rather than at the median response time.

Context length

Each model has a maximum input size, listed on Models. Exceeding it is rejected by the model rather than by Kakehashi, so the message comes from the model and names its own limit.