Errors

Dr.Gero APIs return JSON errors. The exact payload can vary by endpoint, but common fields are:

{
  "error": "message",
  "code": "optional_machine_code",
  "details": {}
}

Common status codes

Status	Meaning	Typical fix
400	Invalid request body, query parameter, or unsupported option.	Validate JSON fields and enum values.
401	Missing or invalid auth.	Add Authorization: Bearer ... with the right token type.
402	Plan or billing limit reached.	Upgrade plan, buy credits, or lower requested resource usage.
403	Token lacks scope or user lacks workspace role/entitlement.	Add scopes or use an admin account.
404	Resource not found.	Check workspace, UUIDs, and endpoint path.
409	Resource not ready or conflict.	Complete prerequisite steps, such as running a leaderboard before inference.
413	Request body too large.	Send smaller batches.
429	Provider or service rate limit.	Retry with backoff.
500/502	Upstream or server error.	Check provider credentials and service logs.

Endpoint-specific examples

Inference before a ranking exists

A leaderboard must have a completed run before /inference can select a model. Run the leaderboard first.

Push dataset rejected rows

A push request can return accepted and rejected counts. Rejections usually come from invalid rows, dataset quotas, or per-request row limits.

Free plan limits

Free workspaces may be limited in:

• Number of leaderboards.
• Leaderboard deletion.
• API token budgets.
• Dataset/trace requests.
• Auto-selected models.

Invalid Hugging Face dataset URL

GET datasets must point to a Hugging Face JSONL file. Use /api/datasets/huggingface/check before creating a leaderboard.

Retry guidance

Retry only idempotent reads and transient provider failures. Avoid retrying write operations without idempotency keys or stable row IDs, especially push dataset ingestion.