Errors & Idempotency

Standard Error Responses

The Nyota API uses conventional HTTP response codes to indicate the success or failure of an API request.

In general:

• Codes in the 2xx range indicate success.
• Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, or a quota was exceeded).
• Codes in the 5xx range indicate an error with Nyota's servers (these are rare).

When an error occurs, the API returns a standard JSON payload:

{
  "success": false,
  "error": "Insufficient Nyota Drive capacity. Please upgrade your storage tier."
}

If you are using our official SDKs, these responses are automatically parsed and thrown as native JavaScript errors (e.g., NyotaDriveError, NyotaRateLimitError).

Rate Limits

To ensure platform stability, the API is rate-limited. By default, API keys are permitted 60 requests per minute.

If you exceed this limit, the API will return a 429 Too Many Requests status code. You should implement exponential backoff in your application to retry requests gracefully.

Idempotency

Network anomalies happen. If your application sends a POST request to create a folder, but the connection drops before you receive the response, you might not know whether the operation succeeded. Safely retrying the request could accidentally create the folder twice.

To prevent this, the Nyota API supports Idempotency Keys.

An idempotency key is a unique value (usually a UUIDv4) generated by your client. If you send a mutating request (POST, PATCH, DELETE) with an x-idempotency-key header, our backend remembers the result of that exact request for 24 hours. If you retry the request with the same key, the backend will return the original successful response without executing the operation a second time.

curl -X POST https://backend.nyotaimara.com/v1/drive/folders \
  -H "x-nyota-api-key: ny_live_..." \
  -H "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"name": "Invoices"}'