Errors

Every failure looks the same. Switch on error.code, it’s stable. Never parse error.message, it’s written for humans and gets reworded freely.

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key does not have the files.delete scope.",
    "status": 403,
    "request_id": "req_8fK2mQ"
  }
}

Every response, success or failure, also carries an X-Request-Id header. Quote it if you report a problem, it maps to the exact log line. If you meet a code you don’t recognize, fall back to the HTTP status. New codes only ever get added, never repurposed, so treating an unknown code by its status is always safe.

Status	Code	When
400	`invalid_request`	The body or a parameter is wrong. The response names the field in `error.param`.
401	`missing_key`	No Authorization header was sent.
401	`invalid_key`	The key is unknown, malformed, or has been revoked.
403	`insufficient_scope`	The key is valid but lacks the scope this endpoint needs.
403	`plan_required`	Your plan has no API access. Free plans have no keys.
403	`key_limit_exceeded`	You hold more keys than your current plan allows, usually after a downgrade. Revoke one or upgrade.
403	`quota_exceeded`	The request would exceed your storage or link allowance.
404	`not_found`	It does not exist, or it is not yours. The two are identical on purpose.
413	`file_too_large`	The file is over your plan’s per-file cap.
429	`rate_limit_exceeded`	You spent your per-key budget. `Retry-After` tells you when to come back.
500	`internal_error`	Something broke on Hypastack’s side. Quote the `request_id` if you report it.
503	`server_busy`	Hypastack is shedding load to stay up. Retry after the window.
503	`service_unavailable`	A dependency is unreachable and Hypastack would rather refuse than guess. Retry shortly.

404 not_found is returned both when something never existed and when it belongs to someone else. That’s on purpose, otherwise anyone with a key could probe ids to discover what other accounts hold.

Guide

Endpoints