Error Handling

The API uses standard HTTP status codes and returns errors as JSON.

Error Format

{
  "error": "Description of what went wrong"
}

Status Codes

Validation Errors

When request body validation fails, the error message describes the first validation issue:

{
  "error": "Expected string, received number"
}

Common Errors

Duplicate evaluator kind (400):

An Agent evaluation plan allows multiple field-level judges. Other kinds support one evaluator each, including disabled entries. Submitting duplicate kinds for those evaluators rejects the entire create or update request before saving changes. The response has error: "duplicate_evaluator_kind" and a top-level message explaining the correction. Multiple field-level judges must have distinct evaluator IDs. Reusing an explicit ID returns error: "duplicate_evaluator_id", with the conflicting id path in details.issues.

The details.issues array identifies each conflict with a path such as ["evaluators", 1, "kind"], its kind, the zero-based firstIndex in the same evaluator list, and a corrective message. Existing details.fieldErrors and details.formErrors remain available. Coding agents should correct the configuration before retrying.

Missing required field:

{ "error": "Required" }

Invalid UUID:

{ "error": "Invalid uuid" }

State conflict:

{ "error": "Can only update pending experiments" }

Billing required (402):

Starting an experiment that uses platform-managed models requires an active subscription and a payment method on the organization:

{
  "error": "Usage billing and a payment method are required for platform model usage."
}

Managed-model actions can also return 402 when the configured monthly managed model soft limit has already been reached before new work starts. In-flight work may still complete and be billed if the limit is crossed during execution.

A free organization is also blocked when its owner already owns another free organization:

{
  "error": "This account already owns another free organization. Upgrade this organization, or the other free organization, to a paid plan to continue."
}

See Billing and pricing for how Promptic Credits, BYOK usage, managed model usage, retention, storage, and usage controls work.

See the full API Reference for endpoint-specific error details.