Troubleshooting

Authentication

AuthenticationError

Cause: Missing or invalid API key. The client raises this immediately if neither the constructor nor RUNRL_API_KEY provides a token.

Fix:

from runrl import RunRLClient
from runrl.exceptions import AuthenticationError

try:
    client = RunRLClient()
except AuthenticationError:
    raise SystemExit("Set RUNRL_API_KEY or pass api_key explicitly.")

Verify the key in the RunRL dashboard or rotate it if you suspect expiry.

AuthorizationError

Cause: Key exists but lacks scopes for the requested action (e.g., uploading files with a read-only key).

Fix: Regenerate the key with write scope or call client.api_keys.update(key_id, scopes=[...]).

File Uploads

ValidationError (422)

Cause: Prompt JSONL is malformed or reward code doesn't define reward_fn correctly.

Checklist:

• Each JSONL line parses individually.
• Prompt entries include a prompt field with message objects.
• Reward function files define def reward_fn(completion, **kwargs): ....

import json

with open("prompt.jsonl") as fh:
    for line in fh:
        json.loads(line)  # raises if invalid

NotFoundError

Cause: Referencing a file that was deleted (soft deletes still hide it from the API).

Fix: Re-upload or list existing files: client.files.list().items.

Run Creation

ValidationError (missing fields)

Cause: Required parameters omitted (model, prompt_file_id, reward_file_id, type).

future = client.runs.create(
    model="Qwen/Qwen2.5-3B-Instruct",
    prompt_file_id="...",
    reward_file_id="...",
    type="reward_function",
)

Ensure file IDs come from File.id, not File.file_id fields belonging to other users.

Futures Stuck Polling

If future.result() appears to hang:

1. Call future.status() to fetch the latest run state.
2. Check client.runs.logs(run_id) for setup errors.
3. Confirm billing status—runs can pause provisioning if billing validation fails.

RunFailedError

Raised when a run terminates in FAILED. Inspect error_message:

from runrl.exceptions import RunFailedError

try:
    run = future.result()
except RunFailedError as err:
    run = err.run
    print(run.error_message)

Network & Rate Limiting

Connection Issues (RunRLException wrapping httpx.RequestError)

• Check proxy/VPN settings.
• Increase timeout: RunRLClient(timeout=60).
• Retry manually; the client already performs exponential backoff.

RateLimitError

Indicates the key exceeded its hourly quota. Monitor the headers (X-RateLimit-Remaining) or lower polling frequency via poll_interval.

Package Import Errors

• Install the SDK in the active environment: pip install runrl.
• If running tests or examples, set PYTHONPATH=. python -m pytest so local modules resolve before publishing.

Getting Help

• For API responses not covered here, log the payload: response.json() using httpx hooks.
• Report SDK bugs or feature requests to support@runrl.com with stack traces and run IDs.