{ "schema_version": "agent-runtime-contract/v1", "errors_endpoint": "https://k-work-trust-api.fly.dev/v1/agent/runtime/errors", "max_payload_size": { "request_body_bytes": 1000000, "response_body_bytes": 1000000, "tool_result_bytes": 1000000, "agent_trust_fetch_bytes": 200000, "unit": "bytes" }, "payload_size_policy": "Before the first mutating or high-volume call, compare expected request, response, and tool-result size against max_payload_size. If the payload may exceed the ceiling, request a smaller projection/page, use a narrower endpoint, or abort and escalate with request_id.", "http_status_routing": { "401": "abort_and_verify_key", "403": "abort_or_correct_policy_violation", "410": "remove_capability_until_manifest_refresh", "422": "correct_input_before_retry", "429": "backoff_or_stop_until_quota_reset", "500": "escalate_with_request_id", "503": "retry_with_backoff_then_escalate" }, "required_public_error_fields": [ "request_id", "error.code", "error.message", "error.failure_mode", "error.retry", "error.agent_next_action", "error.escalation" ], "failure_modes": [ { "code": "UNAUTHORIZED", "applies_to": [ "authenticated_api", "whoami" ], "http_status": 401, "category": "auth_failure", "retry": "do_not_retry_same_key", "agent_next_action": "Abort the protected call, verify the key with /v1/auth/whoami, and obtain a valid key through self-serve signup or the operator.", "escalation": "human_or_operator_if_the_agent_expected_this_key_to_be_active", "safe_to_log": [ "request_id", "error.code" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "RATE_LIMITED", "applies_to": [ "authenticated_api", "signup" ], "http_status": 429, "category": "temporary_limit", "retry": "retry_after_retry_after_seconds", "agent_next_action": "Wait for retry_after_seconds before retrying. If the workflow is urgent or repeated rate limits occur, escalate instead of looping.", "escalation": "human_review_or_alternative_route_for_time_sensitive_workflows", "safe_to_log": [ "request_id", "error.code", "retry_after_seconds" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "QUOTA_EXCEEDED", "applies_to": [ "authenticated_api" ], "http_status": 429, "category": "quota_exhausted", "retry": "do_not_retry_until_resets_at", "agent_next_action": "Stop automated calls for this key until resets_at or ask an operator for review. Do not request a manual key in public channels.", "escalation": "operator_review_required_for_quota_change", "safe_to_log": [ "request_id", "error.code", "quota.limit", "quota.used", "quota.resets_at" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "VALIDATION_BLOCKED", "applies_to": [ "workflow_response" ], "http_status": 200, "category": "business_rule_block", "retry": "retry_only_after_correcting_input", "agent_next_action": "Do not proceed with the workflow action. Preserve blocking_issues and evidence, then collect corrected fields or ask a human reviewer.", "escalation": "human_review_if_the_record_is_business_critical", "safe_to_log": [ "request_id", "status", "decision", "blocking_issues", "warnings" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "MANUAL_REVIEW", "applies_to": [ "workflow_response" ], "http_status": 200, "category": "needs_human_judgment", "retry": "do_not_auto_retry_without_new_information", "agent_next_action": "Route the normalized record, warnings, and evidence to a human reviewer before creating or updating downstream records.", "escalation": "human_review_required_before_downstream_write", "safe_to_log": [ "request_id", "status", "decision", "warnings", "evidence" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "SOURCE_UNAVAILABLE", "applies_to": [ "workflow_response", "official_sources" ], "http_status": 200, "category": "external_source_unavailable", "retry": "retry_later_or_continue_local_only_if_policy_allows", "agent_next_action": "Use local validation only when acceptable. If official-source evidence is required, pause the workflow and escalate with request_id and evidence.", "escalation": "human_or_operator_if_official_source_evidence_is_required", "safe_to_log": [ "request_id", "external_status", "warnings", "evidence" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "PROOF_OF_WORK_FAILED", "applies_to": [ "signup" ], "http_status": 403, "category": "signup_challenge_failure", "retry": "request_fresh_challenge_and_solve_contract", "agent_next_action": "Request a fresh challenge, solve sha256(nonce + ':' + subject + ':' + solution), and avoid repeated blind retries.", "escalation": "only_if_repeated_failures_indicate_onboarding_blocker", "safe_to_log": [ "request_id", "error.code" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "SIGNUP_RATE_LIMITED", "applies_to": [ "signup" ], "http_status": 429, "category": "signup_limit", "retry": "wait_before_requesting_another_challenge_or_mutation", "agent_next_action": "Wait before continuing signup. Do not ask for a pasted plaintext key; use the self-serve flow after the limit resets.", "escalation": "operator_review_only_for_repeated_legitimate_tester_blockers", "safe_to_log": [ "request_id", "error.code" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "ABUSE_GUARD_BLOCKED", "applies_to": [ "authenticated_api", "workflow_request" ], "http_status": 403, "category": "misuse_or_sensitive_input_guard", "retry": "do_not_retry_same_payload", "agent_next_action": "Stop the request. Remove secrets, sensitive personal identifiers, bulk records, or enumeration-like input before retrying with one synthetic or authorized business record.", "escalation": "operator_review_if_the_agent_believes_the_block_is_false_positive", "safe_to_log": [ "request_id", "error.code", "abuse.reason" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets", "personal_identifiers" ] }, { "code": "CAPABILITY_REMOVED", "applies_to": [ "discovery", "agent_routing", "authenticated_api" ], "http_status": 410, "category": "capability_no_longer_available", "retry": "remove_capability_until_manifest_refresh", "agent_next_action": "Remove this capability from the routing cache, refresh the manifest/readiness/runtime contract, and do not call the removed path again unless a newer contract advertises it.", "escalation": "human_or_operator_if_a_live_workflow_depends_on_the_removed_capability", "safe_to_log": [ "request_id", "error.code", "path", "replacement_endpoint" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] } ] }