Responses & Errors - Riona API Docs

Overview

Our API is designed to provide clear, consistent, JSON-formatted responses for both successful requests and errors. This ensures developers can reliably parse responses and handle errors programmatically in their applications. All API responses follow the same structure, consisting of:

Success responses → contain the requested data along with status details.
Error responses → contain standardized error objects with clear messages, and sometimes additional context.

Success Responses

When a request is successful—meaning all required parameters are fulfilled and the request reaches our servers—the API returns an HTTP 200 status code with an ‘OK’ message, along with a JSON object.

Example: Account Balance Request

{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "credits_balance": 5008
}

Error Responses

There are two types of errors you may encounter.

1. Platform-Level Errors

In these cases, the API returns a 200 success status but includes an error message in the response body. These errors are typically related to your plan, product access, or exceeded request limit thresholds.

HTTP Status	Message
200	You don’t have enough credits.
200	Ensure your plan includes access to this product.
200	You have exceeded your plan’s request threshold (requests per minute). Please try again in one minute.
200	Something went wrong.

2. Server Level Errors

If something goes wrong, the API will return an HTTP 4xx or 5xx status code along with a JSON error object.

HTTP Status	Error Code	Description
400	`bad_request`	The request was malformed, Missing API Key or missing required parameters.
401	`unauthorized`	Missing or invalid Bearer Token
403	`forbidden`	You don’t have permission to access this resource (plan restriction).
404	`not_found`	The requested resource could not be found.
409	`conflict`	Request could not be completed due to a conflict (e.g., duplicate entry).
422	`unprocessable_entity`	Request was well-formed but contained invalid data.
500	`internal_server_error`	Unexpected error occurred on our servers. Retry later.
503	`service_unavailable`	API temporarily unavailable (maintenance or overload).