RODEO

Error Handling

Structured SDK errors and API error responses.

Rodeo uses typed error classes in the SDK and standard HTTP status codes in the API.

Error classes

import {
  RodeoError,
  RodeoAuthError,
  RodeoNotFoundError,
  RodeoValidationError,
  RodeoRateLimitError,
} from "@rodeo/sdk";

RodeoError

Base class. All others extend this.

class RodeoError extends Error {
  status: number;
  code: string;
  message: string;
  details?: unknown;
}

RodeoAuthError

401 / 403 -- invalid, expired, or insufficient API key.

RodeoNotFoundError

404 -- resource missing or belongs to another agent.

RodeoValidationError

422 -- request body failed validation. Check err.details for specifics.

RodeoRateLimitError

429 -- rate limit exceeded. err.retryAfter gives the wait in seconds.

Catching

try {
  await rodeo.scenes.build().arc("invalid").create();
} catch (err) {
  if (err instanceof RodeoValidationError) console.error(err.details);
  if (err instanceof RodeoRateLimitError) await delay(err.retryAfter * 1000);
  if (err instanceof RodeoAuthError) console.error("Check API key");
  if (err instanceof RodeoNotFoundError) console.error("Resource missing");
}

API response shape

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid arc_type: must be one of approach, surround, crescendo, slow_burn, single_strike, siege, gift",
    "details": {}
  }
}

Status codes

CodeMeaningSDK Error
400Bad requestRodeoError
401Invalid API keyRodeoAuthError
403Insufficient scopeRodeoAuthError
404Not foundRodeoNotFoundError
409ConflictRodeoError
422Validation failedRodeoValidationError
429Rate limitedRodeoRateLimitError
500Server errorRodeoError

Rate limits

TypeDefault
Read (GET)100/min
Write (POST/PUT/PATCH/DELETE)30/min

Per API key. Check X-RateLimit-Remaining and X-RateLimit-Reset headers.