Response Schema

Overview

How it works

The main risks include silent response drift, clients ignoring unknown fields, undocumented errors, inconsistent numeric precision, and generated code failures. It should cover successful responses and documented error representations. The Response Schema owner should publish stable error semantics and guidance on whether correction, retry, status lookup, or escalation is appropriate.

In production, teams should define ownership and apply status-specific schemas, stable identifiers, explicit nullable fields, error objects, pagination metadata, examples, and compatibility rules. Testing Response Schema should cover malformed input, denied access, rate limits, timeouts, duplicates, asynchronous completion, and version changes.

What matters in practice

A response schema specifies what a client can expect for success and error cases, including identifier formats, status enums, pagination and nullable fields. Clients should not interpret HTTP 200 as proof that an asynchronous payment is complete; it may only mean an instruction was accepted. Unknown enum values and new optional fields should be handled according to documented compatibility rules. Financial responses need precise asset, network, amount and timestamp representations. API providers should describe retryable errors, stable error codes and how to reconcile responses with later webhooks.

For asynchronous payments, a successful creation response should normally expose a stable operation identifier and an explicit state. A finality guarantee should never be inferred from transport-level success. Clients need a defined strategy for unknown future enum values: preserve the raw state, avoid falsely treating it as success and alert operators if necessary. Numeric amounts and fees should carry currency and scale information to avoid silent parsing errors.

Related glossary concepts

Request Schema; Schema Validation; OpenAPI Document