MangaBaka
Sign in
Discord Join our cozy Discord community to chat with like-minded people and stay up to date with MangaBaka (and get the BAKA server tag)

Errors and status codes

How the data and the API work, and why.

Every error comes back as JSON with the HTTP status repeated in the body. Branch on the status and, where present, the code field. The message is for humans and its wording can change.

Error body#↑

{
	"status": 400,
	"message": "Validation error: Unrecognized key: \"foo\"",
	"code": null
}
Field Type Meaning
status number Same as the HTTP status.
message string What went wrong, in plain words. Don't parse it.
code string or null Which rule refused the request, for you to act on. null when none applies.

The schema for a 400 also allows reason and an issues array, where each issue has a code, keys, an optional path and a message. Treat both as optional: query and body validation errors put their details in message.

Status codes#↑

Status Meaning
400 The request is invalid: a bad or unknown parameter, a malformed body, a page past the end.
401 Missing or invalid credentials. See authenticate with a token.
403 Authenticated, but not allowed to do this.
404 The resource doesn't exist.
408 The request timed out.
409 Conflict with the current state. The code says which.
429 Too many requests. See rate limits and caching.
5xx Our side failed. Retry later with backoff.

Each operation in the API reference lists the statuses it can return.

Error codes#↑

Codes are set only where a client can do something specific about the refusal. Today that is mostly stacks: ranked, themed lists of series that readers curate. For example, updating a stack can return stale_token. The reference lists which codes each operation can return.

Code Meaning
stale_token The stack changed since you read it. Read it again and retry with the new token.
duplicate_entry The series is already in the stack.
stack_full The stack already holds the most series it can.
too_few_entries Publishing, or staying published, needs more series that are still on MangaBaka.
series_unavailable A series you added was merged or deleted.
rating_below_floor Too many series are rated above the stack. Raise its content_rating.
rating_below_minimum A moderator set a minimum content_rating for the stack.
stack_locked A moderator locked the stack.
spoiler_locked A moderator locked is_spoiler on.
username_required The owner has to pick a username before the stack is published.
rate_limited You reached the hourly limit for this kind of change. Try again later.

Unknown parameters#↑

Some endpoints reject query parameters they don't define, with a 400 naming the key:

GET /v2/series/search?q=dice&query=dice

{
	"status": 400,
	"message": "Validation error: Unrecognized key: \"query\"",
	"code": null
}

Endpoints that do this include series search, tags, news, publishers, stacks and the source lookups. Others, such as a series by id, ignore unknown parameters.

Don't rely on either behaviour. Send only the parameters the reference lists for the operation.

Errors from the gateway#↑

Rate limiting and an unreachable backend are answered before the request reaches the API. Those bodies have only status and message, no code:

{
	"status": 429,
	"message": "Too Many Requests"
}

A gateway 429 also sends Retry-After: 10. A 429 with "code": "rate_limited" is a different limit: the hourly cap on a kind of write, not the request rate.