Request & Response Model

Design goals

Acceso enforces a unified request and response contract across all endpoints. Clients get predictable envelopes, stable error shapes, and consistent metadata.

• Clients should branch on success, not on ad-hoc fields.

• Errors should be machine-actionable and human-readable.

• Responses should carry correlation and timing metadata.

• Backward compatibility should be explicit and versioned.

Requests are validated against expected parameter schemas. Invalid input returns a structured error before any domain processing occurs.

Request validation

• Required vs optional parameters.

• Type correctness (string vs number vs object).

• Allowed ranges and enums.

• Pagination knobs (limits, cursors, sorting).

• Payload size and content-type.

Treat client-provided values as untrusted. The gateway assumes inputs can be malformed or hostile.

Response envelope

Successful responses use a consistent envelope:

{
  "success": true,
  "data": {},
  "meta": {
    "request_id": "req_xxx",
    "timestamp": 1734160000
  }
}

meta is reserved for platform metadata. Domain data must stay in data.

• request_id: correlation identifier for tracing and support.

• timestamp: server timestamp (epoch seconds).

Pagination conventions

{
  "success": true,
  "data": {
    "items": []
  },
  "meta": {
    "request_id": "req_3d2x",
    "timestamp": 1734160000,
    "pagination": {
      "next_cursor": "cursor_abc",
      "limit": 100
    }
  }
}

Endpoints that return collections should expose pagination in meta. The shape is consistent even when the internal store differs.

HTTP status mapping

HTTP status codes convey broad intent:

• 200 / 201: success.

• 400: invalid request shape or parameters.

• 401: authentication failure (missing or invalid API key).

• 403: authenticated, but not authorized for that API surface.

• 404: resource not found (when applicable).

• 429: rate limited or quota exceeded.

• 500: unexpected platform error.

Error envelope

Internal stack traces and upstream identifiers are intentionally not exposed.

• code: stable identifier for programmatic handling.

• message: safe, user-facing summary.

• details: optional structured context for debugging.

Error fields

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "The request is missing required parameters.",
    "details": {
      "missing": ["address"]
    }
  },
  "meta": {
    "request_id": "req_8m9k2",
    "timestamp": 1734160000
  }
}

Idempotency and retries

For endpoints that mutate state (when supported), use idempotency to make retries safe.

• Client generates an idempotency key per logical operation.

• Client sends it on retries with the same payload.

• Server returns the original result when appropriate.

Example: idempotent request header

POST /v1/defi/some-write HTTP/1.1
Host: <YOUR_ACCESO_API_HOST>
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
Idempotency-Key: 8c3a3fbe-1ab5-4d77-9b10-1ad8b6c51e9f

{"foo":"bar"}