errors and configuration

error handling

every error the sdk raises inherits from RumikError. handle the specific cases you can recover from, like a bad key or a rate limit, and keep RumikError as a backstop so nothing slips through unhandled.

from rumikai import (
    Rumik,
    RateLimitError,
    AuthenticationError,
    UnprocessableEntityError,
    RumikError,
)

client = Rumik()
try:
    audio = client.speech.create(text="Hello")
except AuthenticationError:
    ...  # bad/missing key
except RateLimitError as e:
    wait(e.retry_after)
except UnprocessableEntityError as e:
    print(e.code, e)          # e.g. "text: String should have at most 2000 characters"
except RumikError as e:
    print(f"error {getattr(e, 'request_id', None)}: {e}")

the exception tree

RumikError
├─ APIConnectionError
│  └─ APITimeoutError
├─ APIStatusError
│  ├─ BadRequestError            400
│  ├─ AuthenticationError        401
│  ├─ PermissionDeniedError      403
│  ├─ NotFoundError              404
│  ├─ UnprocessableEntityError   422
│  ├─ RateLimitError             429   (.retry_after)
│  ├─ InternalServerError        500
│  └─ ServiceUnavailableError    503
└─ StreamError

every APIStatusError (the 4xx/5xx group) carries .status_code, .code, .request_id, and .response. RateLimitError adds .retry_after (seconds to wait). passing empty text raises a plain ValueError before any request is sent.

always log request_id so support can trace a failure.

account capacity

429 can also mean your account has reached its purchased concurrent-request capacity. in that case the response code is concurrency_limit_exceeded and the json response includes active_requests and limit:

{
  "error": "Silk is already processing 2 requests for this account. Try again when one finishes, or increase your plan capacity.",
  "code": "concurrency_limit_exceeded",
  "active_requests": 2,
  "limit": 2
}

wait for an active request to finish or increase account capacity. retrying immediately cannot create capacity and never triggers an automatic purchase.

configuration

set these once when you build the client. a few can be overridden per request where it makes sense.

client = Rumik(
    api_key="rk_live_...",              # or RUMIK_API_KEY
    base_url="https://silk-api.rumik.ai",
    timeout=60.0,
    max_retries=2,
    default_headers={"X-App": "my-app"},
)
audio = client.speech.create(text="Hi", extra_headers={"X-Trace-Id": "abc"})
print(audio.request_id)                  # server x-request-id

option	default	description
`api_key`	`RUMIK_API_KEY`	your key.
`base_url`	`https://silk-api.rumik.ai`	api base url (or `RUMIK_BASE_URL`).
`timeout`	`60`	request timeout in seconds.
`max_retries`	`2`	automatic retries on transient errors.
`default_headers`	`None`	headers added to every request.
`http_client`	`None`	supply your own http client.

retries happen automatically on 408, 429, and 5xx responses and on network errors, using jittered exponential backoff and honoring Retry-After. default_headers apply to every request; extra_headers apply to a single call. every response carries a .request_id from x-request-id.

debug logging

set RUMIK_LOG=debug to log every request, response, and retry:

export RUMIK_LOG=debug

debug logging never includes your api key.

documentation

sdk

integrations

cookbook

api reference

error handling

the exception tree

account capacity

configuration

debug logging

​error handling

​the exception tree

​account capacity

​configuration

​debug logging

error handling

the exception tree

account capacity

configuration

debug logging