Errors

Errors use RFC 9457 problem details with Content-Type: application/problem+json:

{
  "type": "https://docs.glitchmug.com/errors/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "Request validation failed",
  "errors": [{ "field": "title", "code": "isLength" }],
  "requestId": "2b5a2d89-3a9f-47b4-9f80-a3b6cc7b7934"
}

• Branch on status and code. title and detail are for people and follow Accept-Language (en, ru).
• errors lists field problems for 422: field is the JSON path (credits.0.name), code the rule that failed. Schema rules use validator names (isLength, isIn, isNotEmpty, whitelistValidation for unknown fields); checks done by the endpoint use short names (required, invalid, https_required).
• Include requestId when you report a bug.

Default codes

When an endpoint has nothing more specific, code follows the status:

Status	code
400	bad_request
401	unauthenticated
403	forbidden
404	not_found
405	method_not_allowed
409	conflict
413	too_large
415	unsupported_type
422	validation_failed
429	rate_limited
451	unavailable_legal (taken down on a copyright notice)
500	internal
503	service_unavailable

Specific codes

Endpoints document their own codes in the reference. The common ones:

code	When
invalid_api_key, scope_missing, banned	See Authentication
invalid_cursor	A cursor that didn't come from page.nextCursor
invalid_idempotency_key	Idempotency-Key isn't 8–128 chars of A-Z a-z 0-9 _ -
idempotency_mismatch	Same Idempotency-Key with a different body
idempotency_in_progress	The first request with this key is still running; retry shortly
search_unavailable	Full-text search (q) is down; filters without q still work
quota_exceeded, file_too_large	Upload over your storage quota or the size limit