Errors

Error handling, error codes, multiple errors, and source pointers

Error Object

An error object describes a single error:

{
  "code": "INVALID_ARGUMENTS",
  "message": "Customer ID must be a positive integer",
  "retryable": false,
  "source": {
    "pointer": "/call/arguments/customer_id"
  },
  "details": {
    "expected": "positive integer",
    "received": -1
  }
}

Fields

Field	Type	Required	Description
`code`	string	Yes	Machine-readable error code. MUST be SCREAMING_SNAKE_CASE.
`message`	string	Yes	Human-readable error description.
`retryable`	boolean	Yes	Whether the client SHOULD retry this request.
`source`	object	No	Location of the error cause.
`details`	object	No	Additional structured error context.

Error Responses

Responses always use the errors field (plural array):

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_123",
  "result": null,
  "errors": [
    {
      "code": "INVALID_ARGUMENTS",
      "message": "Email is required",
      "retryable": false,
      "source": { "pointer": "/call/arguments/email" }
    }
  ]
}

Rules

The errors array MUST contain at least one error
Even single errors use the errors array format

Source Object

The source object pinpoints where the error originated using JSON Pointer (RFC 6901):

Pointer Field

Points to the request field that caused the error:

{
  "source": {
    "pointer": "/call/arguments/customer_id"
  }
}

Common pointer patterns:

Pointer	Description
`/call/arguments/field`	Top-level argument
`/call/arguments/items/0/sku`	Array element field
`/call/arguments/address/city`	Nested object field
`/extensions/0/options/value`	Extension option field
`/context/trace_id`	Context field

Position Field

For parse errors, indicates byte offset:

{
  "source": {
    "position": 142
  }
}

Rules

pointer MUST use JSON Pointer syntax (RFC 6901)
pointer MUST be relative to the request root
position MUST be a zero-indexed byte offset
A source object MUST contain pointer OR position, not both

Standard Error Codes

Protocol Errors

Errors in the Mesh envelope or protocol handling:

Code	Retryable	Description
`PARSE_ERROR`	No	Request is not valid JSON
`INVALID_REQUEST`	No	Request structure violates protocol
`INVALID_PROTOCOL_VERSION`	No	Unsupported protocol version

Function Errors

Errors in function resolution:

Code	Retryable	Description
`FUNCTION_NOT_FOUND`	No	Unknown function name
`VERSION_NOT_FOUND`	No	Unknown version for the function
`FUNCTION_DISABLED`	Yes	Function temporarily disabled
`INVALID_ARGUMENTS`	No	Arguments failed validation
`SCHEMA_VALIDATION_FAILED`	No	Arguments failed schema validation
`EXTENSION_NOT_SUPPORTED`	No	Requested extension not supported

Authentication/Authorization Errors

Code	Retryable	Description
`UNAUTHORIZED`	No	Authentication required or failed
`FORBIDDEN`	No	Authenticated but not permitted

Resource Errors

Code	Retryable	Description
`NOT_FOUND`	No	Requested resource does not exist
`CONFLICT`	No	Operation conflicts with current state
`GONE`	No	Resource existed but was deleted

Operational Errors

Code	Retryable	Description
`DEADLINE_EXCEEDED`	Yes	Request exceeded deadline
`RATE_LIMITED`	Yes	Too many requests
`INTERNAL_ERROR`	Yes	Unexpected server error
`UNAVAILABLE`	Yes	Service temporarily unavailable
`DEPENDENCY_ERROR`	Yes	Downstream service failed

Idempotency Errors

Code	Retryable	Description
`IDEMPOTENCY_CONFLICT`	No	Idempotency key reused with different arguments
`IDEMPOTENCY_PROCESSING`	Yes	Previous request with same key still processing

Async Errors

Code	Retryable	Description
`ASYNC_OPERATION_NOT_FOUND`	No	Unknown operation ID
`ASYNC_OPERATION_FAILED`	No	Async operation failed permanently
`ASYNC_CANNOT_CANCEL`	No	Operation cannot be cancelled (completed or not cancellable)

Batch Errors

Code	Retryable	Description
`BATCH_FAILED`	No	Atomic batch failed (one or more operations failed)
`BATCH_TOO_LARGE`	No	Too many operations or payload too large
`BATCH_TIMEOUT`	Yes	Batch execution exceeded timeout

Custom Error Codes

Applications MAY define additional error codes.

Custom codes SHOULD:

Use SCREAMING_SNAKE_CASE
Be prefixed with application/domain identifier
Be documented for API consumers

Example:

{
  "code": "ORDERS_INVENTORY_INSUFFICIENT",
  "message": "Not enough inventory for SKU WIDGET-01",
  "retryable": false,
  "details": {
    "sku": "WIDGET-01",
    "requested": 10,
    "available": 3
  }
}

Retryable Errors

The retryable field indicates whether clients SHOULD retry:

Retryable (true)

Transient failures that MAY succeed on retry:

DEADLINE_EXCEEDED — Try with longer deadline or later
RATE_LIMITED — Try after backoff
INTERNAL_ERROR — Transient server issue
UNAVAILABLE — Service temporarily down
DEPENDENCY_ERROR — Downstream recovered

Non-Retryable (false)

Permanent failures that MUST NOT succeed on retry:

INVALID_ARGUMENTS — Fix the arguments first
NOT_FOUND — Resource doesn’t exist
FORBIDDEN — Permission denied
CONFLICT — State has changed

Client Behavior

Clients MUST:

Implement exponential backoff for retryable errors
Respect Retry-After hints if provided in details
Set a maximum retry count
NOT retry non-retryable errors

Error Details

The details object provides structured context beyond the message:

Validation Details

{
  "code": "INVALID_ARGUMENTS",
  "message": "Validation failed",
  "retryable": false,
  "source": { "pointer": "/call/arguments/email" },
  "details": {
    "constraint": "email_format",
    "value": "not-an-email"
  }
}

Rate Limit Details

{
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "retryable": true,
  "details": {
    "limit": 100,
    "window": { "value": 1, "unit": "minute" },
    "retry_after": { "value": 5, "unit": "second" }
  }
}

Dependency Details

{
  "code": "DEPENDENCY_ERROR",
  "message": "Payment service unavailable",
  "retryable": true,
  "details": {
    "dependency": "payments-api",
    "dependency_error": "connection timeout"
  }
}

Examples

Single Validation Error

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_123",
  "result": null,
  "errors": [
    {
      "code": "INVALID_ARGUMENTS",
      "message": "Customer ID is required",
      "retryable": false,
      "source": {
        "pointer": "/call/arguments/customer_id"
      }
    }
  ]
}

Multiple Validation Errors

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_456",
  "result": null,
  "errors": [
    {
      "code": "INVALID_ARGUMENTS",
      "message": "Email format is invalid",
      "retryable": false,
      "source": { "pointer": "/call/arguments/email" },
      "details": { "constraint": "email_format" }
    },
    {
      "code": "INVALID_ARGUMENTS",
      "message": "Quantity must be at least 1",
      "retryable": false,
      "source": { "pointer": "/call/arguments/items/0/quantity" },
      "details": { "constraint": "min", "min": 1, "actual": 0 }
    },
    {
      "code": "INVALID_ARGUMENTS",
      "message": "Unknown SKU",
      "retryable": false,
      "source": { "pointer": "/call/arguments/items/1/sku" },
      "details": { "sku": "UNKNOWN-123" }
    }
  ]
}

Parse Error

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": null,
  "result": null,
  "errors": [
    {
      "code": "PARSE_ERROR",
      "message": "Invalid JSON: unexpected token at position 89",
      "retryable": false,
      "source": {
        "position": 89
      }
    }
  ]
}

Rate Limit Error

{
  "protocol": { "name": "mesh", "version": "0.1.0" },
  "id": "req_789",
  "result": null,
  "errors": [
    {
      "code": "RATE_LIMITED",
      "message": "Rate limit exceeded",
      "retryable": true,
      "details": {
        "limit": 1000,
        "window": { "value": 1, "unit": "hour" },
        "retry_after": { "value": 2, "unit": "minute" }
      }
    }
  ]
}