> ## Documentation Index > Fetch the complete documentation index at: https://docs.lumeus.dev/llms.txt > Use this file to discover all available pages before exploring further. # Check RPC liveness > Returns 200 while the RPC process is serving and its database answers. No authentication. It does not say whether the indexed data is current; use `GET /readyz` for that. ## OpenAPI ````yaml /api-reference/rpc.json get /healthz openapi: 3.0.3 info: title: Lumeus RPC version: '2026-09-15' description: >- Lumeus RPC: Stellar JSON-RPC 2.0 over `POST /`, with Lumeus keys, metering and limits. Sign up at https://app.lumeus.dev: Free, Starter, Growth and Scale plans are self-serve, Enterprise by agreement. - **Pricing.** Testnet is free: Testnet requests cost no credits and are never billed. Each organization can make 10,000 Testnet requests a day across Activity, Assets and RPC (unlimited on Enterprise); the count resets at 00:00 UTC, and a request over it answers 429 rate_limited with Retry-After set to the seconds until then. Mainnet requests draw from the plan's monthly credits. A Mainnet call costs its method credits plus one credit per started 64 KiB of response. Each call of a batch counts as one request, and a batch that would cross the daily Testnet cap is refused whole. Plans, limits and credit weights: `GET https://api.lumeus.dev/v1/plans`. - **Authentication.** Send `Authorization: Bearer `. Testnet: `lum_test_…`; Mainnet: `lum_live_…`. A key works only on its own network, so pick the server that matches it (the other network answers 401). Publishable `lum_pub_…` keys call read-only methods only, from an allowed browser origin. Dashboard sessions and webhook keys are not accepted. - **Headers.** Every response carries X-Request-Id; authenticated responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; 429 and 503 carry Retry-After. - **Errors.** JSON-RPC 2.0 error objects. Gateway errors carry the machine-readable code as the string error.data and the request ID as error.request_id (see [errors](/guides/errors)). A JSON-RPC error can arrive with HTTP 200, from the node or for one call of a batch, so check error before reading result. The REST routes (`/operations/...`, `/healthz`, `/readyz`) answer flat JSON errors. - **CORS.** Browser calls (CORS) are allowed from https://docs.lumeus.dev (the Try it playground of this reference) and https://app.lumeus.dev only, without cookies; responses expose ETag, Link, Location, Retry-After, X-Request-Id, X-Lumeus-Operation-Id, X-Lumeus-Idempotency and RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (errors included). Other websites cannot read responses made with a server key: use a publishable key with your own allowed origins ([browser keys](/guides/browser-keys)). license: name: Lumeus API contract servers: - url: https://rpc-testnet.lumeus.dev description: Testnet (default) - url: https://rpc.lumeus.dev description: Mainnet security: - Bearer: [] tags: - name: JSON-RPC description: >- Stellar JSON-RPC 2.0 over `POST /`: one call or a batch of up to 20. Each method has its own page with parameters, result fields and a real response. - name: Results description: >- Recover the saved result of a long prepaid call without running it again. Only prepaid accounts receive operation IDs; every other account gets 404 here. - name: Health description: Liveness and readiness probes for monitoring. No authentication. paths: /healthz: get: tags: - Health summary: Check RPC liveness description: >- Returns 200 while the RPC process is serving and its database answers. No authentication. It does not say whether the indexed data is current; use `GET /readyz` for that. operationId: checkRpcLiveness responses: '200': description: The process is serving and its database answers. content: application/json: schema: type: object properties: status: type: string description: ok, or db unavailable on 503. service: type: string description: The answering service. required: - status example: status: ok service: rpc-gateway headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ '405': $ref: '#/components/responses/HTTP405_4' '503': $ref: '#/components/responses/HTTP503_4' security: [] x-codeSamples: - lang: bash label: cURL source: curl --fail-with-body -sS 'https://rpc-testnet.lumeus.dev/healthz' - lang: javascript label: JavaScript source: |- // Node 18+ (ES module) const res = await fetch('https://rpc-testnet.lumeus.dev/healthz', { method: 'GET', }); console.log(res.status, JSON.stringify(await res.json(), null, 2)); - lang: python label: Python source: |- import json import requests res = requests.get( "https://rpc-testnet.lumeus.dev/healthz", timeout=30, ) print(res.status_code, json.dumps(res.json(), indent=2)) components: responses: HTTP405_4: description: >- This path does not accept the HTTP method you sent (code method_not_allowed). The Allow header lists the methods it accepts. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: method_not_allowed error: 'method POST is not allowed on /healthz; allowed: GET, HEAD' request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ HTTP503_4: description: The billing database is unavailable (error.data unavailable). content: application/json: schema: $ref: '#/components/schemas/RPCResponse' example: jsonrpc: '2.0' id: null error: code: -32000 message: billing database unavailable data: unavailable request_id: req_6f1c2a9b0e4d4c7a8b3f5e21 headers: X-Request-Id: description: >- Identifier of this request: req_ followed by 24 hex characters. Error bodies repeat it as request_id. Quote it when contacting support. schema: type: string pattern: ^req_[0-9a-f]{24}$ schemas: Error: type: object properties: error: type: string description: Human-readable message. It may change; branch on code. code: type: string description: >- Machine-readable error code. Branch on code, not on the error text, which may change. RPC carries the same codes as the string error.data of a JSON-RPC error. invalid_request: 400: invalid input, including a malformed Idempotency-Key or an unknown or repeated query parameter (Webhooks also uses it for an oversized request body, 413). Fix the request; do not retry unchanged. unauthorized: 401: missing, revoked, invalid or wrong-network credential. payment_required: 402 (Mainnet): monthly credit quota exhausted on a hard-capped plan. forbidden: 403: the key or account policy does not allow this action. not_found: 404 (Webhooks also 410): the resource does not exist in this organization and network. topic_search_disabled: 404: contract-event topic search is not enabled on this network. method_not_allowed: 405: the route does not accept this method. conflict: 409: conflicting request identity, idempotency key, funding or recovery state. generation_changed: 409: the index generation or network changed since the snapshot was taken; restart the walk without generation and snapshot_ledger. history_unavailable: 409 (Assets): as_of_ledger is not answered from the balance history; start a snapshot job (POST /snapshots) or retry later. precondition_failed: 412 (Webhooks): the subscription version changed; fetch the current ETag. response_too_large: 413: the result exceeds the response budget; lower limit or narrow the request. precondition_required: 428 (Webhooks): If-Match with the subscription ETag is required. rate_limited: 429: a rate, concurrency or credit-cap limit was reached, or (Activity, Assets and RPC on Testnet) the daily Testnet request cap (message `daily Testnet request cap of 10000 reached; resets at 00:00 UTC`, Retry-After until 00:00 UTC). Wait Retry-After seconds (a refused request consumes nothing). A Retry-After greater than 60 means the daily Testnet cap: wait until 00:00 UTC or switch to Mainnet. RPC carries it as the string error.data. internal_error: 500 or another unexpected 5xx; quote request_id when contacting support. not_implemented: 501: the feature is not enabled on this host. busy: 503: reads are saturated (the queue wait expired or the database refused another query or ran short of memory). Retry the same request after Retry-After (2) seconds. query_timeout: 503: the read ran out of time. Do not retry unchanged right away: narrow the ledger range (since_ledger/until_ledger) or lower limit; Retry-After is 30. index_not_ready: 503: the index or snapshot is not ready yet or is rebuilding; retry after Retry-After seconds. topic_coverage: 503: the effective range is outside the contract-event topic index coverage (the message states it); pass a range inside it or retry after Retry-After (60) seconds. unavailable: 503: another temporary failure (billing, rate limiter, queue); retry after Retry-After seconds. enum: - invalid_request - unauthorized - payment_required - forbidden - not_found - topic_search_disabled - method_not_allowed - conflict - generation_changed - history_unavailable - precondition_failed - response_too_large - precondition_required - rate_limited - internal_error - not_implemented - busy - query_timeout - index_not_ready - topic_coverage - unavailable request_id: type: string description: >- Identifier of this request, the same value as the X-Request-Id header. Quote it when contacting support. required: - error RPCResponse: type: object properties: jsonrpc: type: string enum: - '2.0' id: type: integer description: >- The id of your call, echoed unchanged (a string id comes back as a string). null when the gateway cannot read the id, for example for invalid JSON. nullable: true result: type: object additionalProperties: true description: >- The method result, as returned by stellar-rpc 29. Its fields depend on the method: see the method pages (for example [getHealth](/api/rpc/getHealth) or [getEvents](/api/rpc/getEvents)) or the components named after the method with a Result suffix (getHealthResult, getEventsResult, ...). error: $ref: '#/components/schemas/RPCError' required: - jsonrpc - id oneOf: - title: Result required: - result not: required: - error - title: Error required: - error not: required: - result description: >- A JSON-RPC 2.0 response: result on success, error otherwise. A JSON-RPC error can arrive with HTTP 200 (for example from the node, or for one child of a batch). Gateway errors carry the code string in error.data and the request ID in error.request_id; they echo your id when the body is a parseable single request and use a null id when it cannot be determined. Preserve integer IDs exactly; avoid unsafe JavaScript numeric IDs. The gateway never answers 502 or 504. RPCError: type: object properties: code: type: integer description: >- JSON-RPC code. Gateway errors: -32700 parse error, -32600 invalid request (also a body over 1 MiB), -32601 unsupported method, -32602 invalid params, -32000 policy or availability (401, 402, 403, 413 response too large, 429, 503). Errors from the Stellar node keep its own code. message: type: string description: Human-readable; may change. Branch on data. data: type: string description: >- Gateway errors: the machine-readable code as a plain string, so that every Stellar SDK can parse it. The values are the shared error codes plus submission_outcome_unknown. Errors from the Stellar node keep the node's own data, if any. invalid_request: 400: invalid input, including a malformed Idempotency-Key or an unknown or repeated query parameter (Webhooks also uses it for an oversized request body, 413). Fix the request; do not retry unchanged. unauthorized: 401: missing, revoked, invalid or wrong-network credential. payment_required: 402 (Mainnet): monthly credit quota exhausted on a hard-capped plan. forbidden: 403: the key or account policy does not allow this action. not_found: 404 (Webhooks also 410): the resource does not exist in this organization and network. method_not_allowed: 405: the route does not accept this method. conflict: 409: conflicting request identity, idempotency key, funding or recovery state. response_too_large: 413: the result exceeds the response budget; lower limit or narrow the request. rate_limited: 429: a rate, concurrency or credit-cap limit was reached, or (Activity, Assets and RPC on Testnet) the daily Testnet request cap (message `daily Testnet request cap of 10000 reached; resets at 00:00 UTC`, Retry-After until 00:00 UTC). Wait Retry-After seconds (a refused request consumes nothing). A Retry-After greater than 60 means the daily Testnet cap: wait until 00:00 UTC or switch to Mainnet. RPC carries it as the string error.data. internal_error: 500 or another unexpected 5xx; quote request_id when contacting support. unavailable: 503: another temporary failure (billing, rate limiter, queue); retry after Retry-After seconds. submission_outcome_unknown: 503 (RPC sendTransaction only): the transaction reached the node but its answer was lost; poll getTransaction with error.transaction_hash before building a new transaction. Resubmitting the same signed envelope is safe (the node answers DUPLICATE). request_id: type: string description: >- Gateway errors: the same value as the X-Request-Id header; quote it when contacting support. transaction_hash: type: string description: >- submission_outcome_unknown only: the hash of the submitted transaction. Poll getTransaction with it. required: - code - message example: code: -32000 message: valid API key required data: unauthorized request_id: req_0123456789abcdef01234567 securitySchemes: Bearer: type: http scheme: bearer description: >- Send `Authorization: Bearer `. Testnet: `lum_test_…`; Mainnet: `lum_live_…`. A key works only on its own network, so pick the server that matches it (the other network answers 401). Publishable `lum_pub_…` keys call read-only methods only, from an allowed browser origin. Dashboard sessions and webhook keys are not accepted. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.