Errors and limits

Error format

Every API error is a machine code plus one plain sentence.

{
  "error": "invalid_credentials",
  "message": "Username or password is incorrect. Next attempt in 4 seconds.",
  "retry_after": 4
}

retry_after is present when the caller should back off. The same value is sent in the Retry-After header.

Error codes

code	HTTP	meaning
`invalid_request`	400	a required field is missing or malformed
`invalid_client`	401	unknown app, disabled app, or bad app secret
`invalid_credentials`	401	wrong username or password
`invalid_grant`	400	code invalid, expired or used, or the user is inactive
`invalid_token`	401	missing, expired or revoked token
`too_many_attempts`	429	in cooldown, honour `retry_after`
`weak_password`	400	below the minimum length
`forbidden`	403	the token cannot do that
`not_found`	404	no such object in your scope
`conflict`	409	the username is already taken
`unsupported_grant_type`	400	unknown `grant_type`
`bad_origin`	403	the request came from an unexpected origin
`server_error`	500	unexpected failure

Password rules

Minimum length is 10 characters.
Usernames are 3-32 characters: letters, digits, dot, underscore or hyphen.
App usernames follow the same rule and are unique within an app.

Client account sign-ins

Client sign-ins are strictly rate-limited. The wait doubles after each failed attempt: 1, 2, 4, 8, 16, 32, 64 seconds and so on. There is no practical cap.

If a client account is locked out, contact your administrator to clear it.

App user sign-ins

App user sign-ins are lenient by default. The first few failures are free, then the wait doubles up to the app's cap.

field	default	bounds
`start_after`	5	0-20
`cap`	60	5-300 seconds
`burst_gap`	300	60-3600 seconds

You can tune these per app with PATCH /manage/settings.

Retry behaviour

Read retry_after or the Retry-After header.
Do not retry a 4xx blindly. Fix the request first.
Retry a 5xx with exponential backoff and jitter.
Treat invalid_token as a signal to re-authenticate, not to retry the same call.

Content types

The token and management endpoints accept application/json or form-encoded bodies. Send Content-Type: application/json when you send JSON.

Request size

JSON and form bodies are read as a flat dictionary. Send one object per request. Do not send nested arrays where a string is expected.

GAUTH