orgasm.dev

Errors

Problem details, every error code and what to do about it, retries and idempotency.

Errors are RFC 9457 problem details, served as application/problem+json:

{
  "type": "https://orgasm.dev/docs/guides/errors#consent_required",
  "title": "Consent is required",
  "status": 422,
  "code": "consent_required",
  "detail": "consent.subjectIsAdult and consent.subjectConsented must both be true, and consent.ageVerification must say how age was verified.",
  "param": "consent",
  "instance": "/v1/live-sessions",
  "requestId": "req_3k6m9q2t5w8z1c4f7h0j"
}

Switch on code, which is stable; show detail to developers, not to end users. param names the field at fault. When a request breaks the contract, errors lists each violation with its location, JSON path and message. Every response carries Request-Id; include it when you ask for help.

Codes

invalid_request

400 or 422. The body is not JSON, or a parameter or field breaks the contract. Fix the request; errors and param say where.

422. consent.subjectIsAdult or consent.subjectConsented is not true, or consent.ageVerification is missing. Only set them when your product has verified both; see acceptable use.

capability_required

422. A live session created with a live key needs capabilityHash from the device.

sandbox_only

422. sandbox options were sent with a live key.

authentication_required

401. No key was sent. Send Authorization: Bearer sk_test_….

invalid_api_key

401. The key or client token is malformed, revoked, or belongs to no session.

live_mode_unavailable

403. A live key cannot do this yet: today, recorded videos (createRecording), which the sandbox analyses meanwhile with a key that starts with sk_test_. Every live request answers it while live analysis is switched off.

credits_exhausted

402. Your company has no credits left, so a new live session does not start. Sessions already running finish, and test keys still reach the sandbox. Buy a package through sales@orgasm.dev: live sessions start again as soon as it posts. Do not retry until then. Credits and billing explains the balance and credits.low, which warns you before zero.

permission_denied

403. The credential cannot do this; a client token, for example, only reads its own session, and a sandbox key that belongs to no company has no credits to read.

not_found

404. No such resource in this key's mode, or it was deleted.

idempotency_key_reused

409. The Idempotency-Key was used with a different body. Use a new key for a new request.

session_ended

409. The session has ended; create a new one.

sandbox_no_media

501. The sandbox accepts no media; its sessions play their scenario on their own.

upload_already_received

409. The upload URL was already used; submit a new recording to upload again.

payload_too_large

413. The upload is larger than maxBytes.

rate_limited

429. Too many requests. Wait Retry-After seconds. RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset are on every response.

capacity_unavailable

503. No analysis capacity is free. Retry after Retry-After seconds.

internal_error

500. Something failed on our side. Retry with the same Idempotency-Key.

Retries and idempotency

Send an Idempotency-Key (a UUID) with every POST. A retry with the same key and body within 24 hours returns the first response, marked Idempotent-Replayed: true, instead of acting twice. Retry 429, 500 and 503 with exponential backoff; do not retry other 4xx, 402 included, without changing the request or the balance.

On this page