Errors & pagination

Every error uses the same JSON shape, with a code you can switch on.

{
    "error": {
        "code": "insufficient_scope",
        "message": "This credential lacks the required scope: profile.read.",
        "request_id": "req_8f2k3m9x1q4w7e5r6t0y"
    }
}

HTTP	code	Meaning
401	`unauthenticated`	No Authorization header, or it isn't a bearer token.
401	`invalid_token`	Unknown, expired or revoked key or token.
403	`insufficient_scope`	The credential is valid but lacks the scope for this endpoint.
403	`forbidden`	Not allowed, e.g. a live key on an account without approved API access.
403	`live_key_required`	A test key called an endpoint that changes real data. Use a live key.
403	`not_a_seller`	The account doesn't own (or work for) an approved store.
404	`not_found`	No such endpoint or resource.
405	`method_not_allowed`	Wrong HTTP method.
409	`invalid_state`	The resource can't make that change now, e.g. shipping an order that's already shipped or cancelled.
422	`validation_failed`	A parameter is invalid; see error.details.
429	`rate_limited`	Too many requests; wait Retry-After seconds.
500	`server_error`	Our fault. Retry with backoff and quote the request_id if it persists.

Pagination

List endpoints accept page and per_page (max 100) and return meta and links:

{
    "data": [
        "\u2026"
    ],
    "meta": {
        "page": 2,
        "per_page": 20,
        "total": 57,
        "last_page": 3
    },
    "links": {
        "next": "https://developers.vaxhost.com/api/v1/apps?page=3",
        "prev": "https://developers.vaxhost.com/api/v1/apps?page=1"
    }
}

Request IDs

Every response has an X-Request-Id header (you may send your own). Include it when you contact support.