API credits, balances, and settlement
Check your Rivya API credit balance, understand generation reservations and chat charges, and distinguish task failure from credit settlement and refunds.
Last reviewed on November 5, 2026
Rivya Public API and Studio use the credit balance on the same account. API keys do not have separate wallets. The balance can include eligible signup grants, subscription credits, purchased credit packs, and returned task credits.
Use GET /api/v1/credits to read the stored balance for the API key's account. Credit amounts and expiry depend on how they were granted; sharing a wallet does not remove those conditions. See Credits & Billing in Rivya.
Endpoint
The key needs credits:read or the wildcard scope *. See API key authentication for key creation, permissions, expiry, and revocation.
Endpoint notation:
GET https://rivya.ai/api/v1/creditsRequired HTTP header:
Authorization: Bearer rvya_sk_...Replace the header placeholder with your own key. If RIVYA_API_KEY is already set in your server environment, you can make the request with:
curl https://rivya.ai/api/v1/credits \
-H "Authorization: Bearer $RIVYA_API_KEY"Keep the secret key on the server; do not put it in browser code or a public repository.
Response
Example response; 123 is an illustrative balance:
{
"current_credits": 123
}current_credits is a snapshot of the stored account balance. This endpoint does not list individual credit grants, expiry dates, reservations, or task settlements. If the account has no balance record, it returns 0; a database failure returns an API error instead.
The balance can change as Studio or API requests use credits, expiry is processed, or grants and returns are recorded. Credit expiry is checked when a reservation is deducted. A balance check does not reserve credits or guarantee that a later request can start.
A positive balance also does not make every listed model callable. Check the model's api_status and your key's request permissions in Model discovery before submitting work.
Generation Billing
A new generation must have enough credits for its initial reservation. Rivya checks and deducts those credits before sending the provider request. The required amount depends on the selected model, inputs, and settings.
The generation response includes:
reserved_credits: the initial amount reserved for the task, not a universal model price.final_credits: the amount currently recorded for the task. It can equal the reservation while the job is queued or processing; it is not necessarily0.
Read settlement_status before treating final_credits as settled usage:
PENDINGorRESERVED: final settlement has not been recorded.SETTLED: usage has been settled. If valid final usage is below the reservation, the difference is returned to the account.RECONCILIATION_REQUIRED: final usage is missing, invalid, or greater than the reservation. The reservation remains recorded; this state does not automatically charge the excess.
A generation can be succeeded while its credits still need settlement. Generation progress and credit settlement are separate states.
Once the reservation has been deducted, the wallet balance already reflects it. Do not subtract reserved_credits from a later current_credits balance again.
Chat Billing
POST /api/v1/chat/completions uses the same account balance. Rivya deducts an initial reservation for a new turn before contacting the chat provider. The response reports credits.reserved, credits.final, and credits.settlement_status.
The usage object reports token counts when available. Token counts alone are not the charged credit amount; read the credit fields and their settlement status. For GPT-5.2, a complete response with confirmed, consistent token counts can settle at its model credit rates when no explicit consumption is reported. An invalid explicit consumption value still requires reconciliation. A returned reply can still have RECONCILIATION_REQUIRED, which means its credits have not been settled.
A failed HTTP request does not by itself tell you whether the turn was committed or a credit return was recorded. Check the existing session and follow Chat API and API Errors and Limits before sending another paid turn.
Failed Jobs
A failed task and returned credits are different events. For an existing generation, check settlement_status together with task status:
REFUNDED: the reserved credits were returned to the account.FAILED: no refund was recorded for the task. This settlement value is separate from taskstatus: failed; it does not by itself prove that credits were deducted.
Elapsed time or an error while checking status is not proof that a generation failed or its credits were returned. Keep the existing task ID and follow Generation Status and Failed Tasks and Credit Refunds.
A task credit return is separate from a refund of a subscription or credit-pack payment.
Common Credit Errors
These errors can affect balance checks or charged requests; they do not all come from the balance endpoint:
insufficient_credits(402): the account cannot cover the request's credit reservation. Check the balance, required credits, and expiry before retrying. Reading the balance does not require a positive balance.api_key_invalid(401): the supplied key is invalid. Missing, expired, or revoked keys useapi_key_missing,api_key_expired, orapi_key_revokedinstead.api_scope_denied(403): the key lacks the required permission. Reading the balance needscredits:reador*.public_api_disabled(503): Public API access is disabled or key authentication is unavailable. No account balance is returned.internal_error(500): the request could not be completed. If a balance check fails, do not treat the error as a balance of0.
For the error response format, request IDs, and retry conditions, see API Errors and Limits.
