Reference

Errors

Stable error codes, HTTP statuses, gRPC mappings, retry guidance, reason codes, field paths, correlation IDs, and explainability links.

Every Vadyl surface returns a typed error envelope. Human-readable messages may improve over time; code, reasonCode, field, correlationId, and retry classification are the stable integration contract.

Error envelope

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Order.total must be greater than zero.",
    "reasonCode": "Order.Validation.Total.NonPositive",
    "field": "total",
    "retryable": false,
    "correlationId": "01HXZ0J4YV8AJF2GFG2T1F7Y42",
    "explainUrl": "/api/Explainability/access/read?correlationId=01HXZ0J4YV8AJF2GFG2T1F7Y42",
    "details": {
      "entity": "Order",
      "operation": "Create"
    }
  }
}

Catalog

Status	Code	Meaning	Retry
`400`	`BAD_REQUEST`	Malformed JSON, invalid enum literal, unknown route binding, or impossible request shape.	Fix request before retrying.
`401`	`UNAUTHORIZED`	Missing, expired, malformed, or unsupported authentication material.	Refresh token or repair credentials.
`403`	`ACCESS_DENIED`	Authenticated actor lacks the required grant, row predicate, field permission, scope, or envelope authority.	Do not retry without a permission or input change.
`404`	`NOT_FOUND`	Resource is absent or hidden by access policy.	Re-read list/search or verify actor scope.
`409`	`CONFLICT`	Optimistic concurrency mismatch, unique-key collision, branch/proposal conflict, dependency conflict, or irreversible effect conflict.	Usually re-read and retry with a new concurrency token.
`412`	`PRECONDITION_FAILED`	If-Match, publication pin, branch head, approval gate, or compatibility precondition failed.	Refresh authority state and retry if still intended.
`422`	`VALIDATION_FAILED`	Entity validation, AST validation, capability validation, policy grammar, schema transition, or typed payload validation failed.	Fix the typed input.
`429`	`QUOTA_EXCEEDED`	Hard quota, rate limit, token budget, runtime budget, or plan reservation exceeded.	Retry after reset only when headers or quota policy allow.
`503`	`UPSTREAM_UNAVAILABLE`	Provider, connector, model, storage, cache, or runtime substrate unavailable.	Retry with backoff when idempotency guarantees exist.
`504`	`UPSTREAM_TIMEOUT`	Connector/runtime/provider call exceeded the platform or declared egress deadline.	Retry only idempotent operations or provide Idempotency-Key.
`gRPC`	`PERMISSION_DENIED`	gRPC projection of ACCESS_DENIED with Vadyl error details.	Same as ACCESS_DENIED.

Examples

BAD_REQUEST

{ "error": { "code": "BAD_REQUEST", "message": "Invalid filter JSON" } }

UNAUTHORIZED

{ "error": { "code": "UNAUTHORIZED", "reasonCode": "Auth.MissingBearer" } }

ACCESS_DENIED

{ "error": { "code": "ACCESS_DENIED", "reasonCode": "Access.DeniedByPolicy" } }

NOT_FOUND

{ "error": { "code": "NOT_FOUND", "resource": "Order", "id": "ord_missing" } }

CONFLICT

{ "error": { "code": "CONFLICT", "reasonCode": "Concurrency.TokenMismatch" } }

PRECONDITION_FAILED

{ "error": { "code": "PRECONDITION_FAILED", "expected": "pub_412", "actual": "pub_413" } }

VALIDATION_FAILED

{ "error": { "code": "VALIDATION_FAILED", "field": "total", "reasonCode": "Order.Total.NonPositive" } }

QUOTA_EXCEEDED

{ "error": { "code": "QUOTA_EXCEEDED", "quota": "read.monthly" } }

UPSTREAM_UNAVAILABLE

{ "error": { "code": "UPSTREAM_UNAVAILABLE", "provider": "stripe", "retryable": true } }

UPSTREAM_TIMEOUT

{ "error": { "code": "UPSTREAM_TIMEOUT", "deadlineMs": 30000 } }

PERMISSION_DENIED

code: PERMISSION_DENIED
details: { code: "ACCESS_DENIED", reasonCode: "Access.DeniedByPolicy" }

GraphQL mapping

{
  "data": { "orders": null },
  "errors": [{
    "message": "Access denied",
    "path": ["orders"],
    "extensions": {
      "code": "ACCESS_DENIED",
      "reasonCode": "Access.DeniedByPolicy",
      "correlationId": "01HXZ0J4YV8AJF2GFG2T1F7Y42"
    }
  }]
}

gRPC mapping

Vadyl code	gRPC status
`UNAUTHORIZED`	`UNAUTHENTICATED`
`ACCESS_DENIED`	`PERMISSION_DENIED`
`NOT_FOUND`	`NOT_FOUND`
`CONFLICT`	`ABORTED`
`VALIDATION_FAILED`	`INVALID_ARGUMENT`
`QUOTA_EXCEEDED`	`RESOURCE_EXHAUSTED`
`UPSTREAM_TIMEOUT`	`DEADLINE_EXCEEDED`

Retry contract

Retry only when the error is marked retryable or when the operation is idempotent and you supplied an Idempotency-Key. Writes, external egress, workflow signals, webhook replays, agent tool calls, and deployment commands should always carry an idempotency key when a client might retry.

SDK reference model

Limits & quotas