Error reference

Every refusal body is application/problem+json with the keys type, title, status, detail, code, and fix. Clients should branch on code, never on detail.

MCP tool errors carry the same code and fix beside their coarse error.

Example

{
  "type": "https://docs.acretix.io/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "insufficient_scope:verify:submit",
  "code": "insufficient_scope",
  "fix": "Use a key that carries the scope named after the colon in detail, or add that scope to this key in the console."
}

Refusal codes

Every refusal code, its status, its cause and what to do
Code	Status	Cause	What to do
`api_key_expired`	401	The API key has passed its expiry time.	Create a new key for this project, or use a key that has not expired.
`callback_url_needs_webhook_endpoint`	400	A callback URL was sent but the account has no active webhook endpoint to sign it.	Register a webhook endpoint first; its secret signs callbacks.
`conflict`	409	The request conflicts with the current resource state.	Refresh the resource state and retry the request.
`conflicting_labels`	400	Rubric induction examples assign conflicting labels.	Resolve the conflicting labels and try again.
`description_too_vague`	400	The description is empty or too vague to draft criteria from.	Describe the work and what counts as done in plain sentences, then try again.
`determination_already_recorded`	409	A determination is already recorded for this verification.	Read the recorded determination with GET /v1/verifications/{id}/determination; a verification takes one customer determination.
`escalation_not_found`	404	The escalation does not exist or is not waiting for Acretix review.	List the escalations waiting for Acretix review and use an id from that list.
`forbidden`	403	The API key is not allowed to perform this operation.	Use a key authorized for this operation.
`idempotency_key_conflict`	409	The Idempotency-Key was reused with a different request payload.	Send the original payload again, or use a new Idempotency-Key for a different request.
`identity_contract_tenant_mismatch`	403	The identity contract tenant assertion does not match the authenticated key.	Use the tenant bound to the authenticated identity contract key.
`induction_failed`	422	The service could not produce a rubric induction result.	Review the examples and try the induction request again.
`insufficient_scope`	403	The API key does not carry the required scope.	Use a key that carries the scope named after the colon in detail, or add that scope to this key in the console.
`internal_error`	500	The service encountered an unexpected internal error.	Retry later, and contact support if the problem persists.
`invalid_callback_url`	400	The callback URL does not meet the delivery requirements.	Use a valid public HTTPS callback URL.
`invalid_idempotency_key`	400	The Idempotency-Key header is outside the accepted length.	Send an Idempotency-Key between 1 and 255 characters.
`invalid_identity_rung`	400	The identity_rung value is not supported.	Use one of the documented identity_rung values.
`invalid_input_roles`	400	The rubric induction request has invalid input roles.	Correct the induction request fields and try again.
`invalid_json`	400	The request body is not valid JSON.	Send a syntactically valid JSON request body.
`invalid_label`	400	A rubric induction example has an unsupported label.	Use one of the documented example labels.
`invalid_request`	400	The request does not satisfy the API input requirements.	Correct the request fields and submit it again.
`judgment_already_closed`	409	The escalation already has a closing judgment.	Read the escalation and submit no further closing judgment.
`judgment_capacity_not_admitted`	422	The judge capacity is not admitted by the judgment rule.	Use a capacity admitted by the subject rule.
`judgment_criterion_unknown`	422	The judgment names a criterion the subject does not have.	Name only a criterion present on the subject.
`judgment_minutes_invalid`	422	The reviewer minutes are not valid for this judgment.	Send whole minutes worked, at least 1.
`judgment_rule_stale`	409	The supplied judgment rule does not match the escalation.	Read the escalation again and send the rule it names.
`judgment_rule_unknown`	422	The judgment rule is not carried by this API version.	Send a judgment using a rule carried by this API version.
`judgment_shape_invalid`	400	The judgment does not satisfy the required record shape.	Correct the judgment fields to match the rule and capacity.
`judgment_signature_invalid`	422	The judgment signature could not be verified.	Sign the judgment with the credential authorized for this judge.
`judgment_tier_unknown`	422	The reviewer tier is not recognized by this API version.	Use a tier in the current version of GET /v1/reviewer-tiers.
`judgment_time_outside_window`	422	The judgment time is outside the escalation review window.	Set judged_at between the escalation reaching stage human and the request.
`not_found`	404	The requested resource was not found.	Confirm the resource identifier and try again.
`payload_too_large`	413	The request body exceeds the supported size limit.	Reduce the request body size and try again.
`rate_limited`	429	The request rate limit has been reached.	Wait for the retry interval and submit the request again.
`service_unavailable`	503	The requested feature is not currently available.	Retry when the feature is available.
`too_few_examples`	400	The rubric induction request does not include enough examples.	Provide at least three labeled examples and try again.
`too_many_examples`	413	The rubric induction request includes too many examples.	Reduce the number of examples and try again.
`unauthorized`	401	The API key is missing, invalid, or inactive.	Send an active API key in the Bearer authorization header.
`unprocessable`	422	The request is valid but cannot be processed by this API version.	Change the unsupported request option and try again.
`untrusted_request_source`	403	The request source could not be established.	Send the request through a trusted source.

Command-line exit codes

The acretix-verify command-line tool ends with one of these codes. Its help text, acretix-verify --help, lists the same codes.

Every exit code of the command-line tool, what it means and what to do
Exit code	Meaning	What to do
0	met/valid	Nothing to do: the work met the rubric, or the saved proof checked out.
1	usage or local refusal	Read the message on stderr, then fix the command, its flags or the local file it names.
2	not_met	Read each criterion and its reason in the output, change the work, then run again.
3	partial	Read the criteria that were not met, then change the work or decide whether a partial verdict is enough for this job.
4	cannot_determine	Read each criterion and its reason: the submission did not carry enough to decide. Send the work the rubric asks about, then run again.
5	timeout	The verification did not finish within --timeout seconds. Run again with a larger --timeout.
6	API refusal	The API refused the request. Its refusal code and fix are on stderr. See Refusal codes.
7	failed status	The verification ended with status failed and no verdict. Run it again.
8	invalid proof	The saved proof did not check out; the reason follows the word invalid on stderr. Do not rely on that proof.