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.
consent_required
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.
Teams and roles
Your company's people on orgasm.dev, as Admins, Developers and Billing members. Covers invitations and requests to join, who owns keys and endpoints, rolling keys and webhook secrets, and the activity log.
Sandbox
The deterministic scenarios behind test keys, how to choose and speed them up, and how the sandbox differs from live analysis.