> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.crisscross.money/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.crisscross.money/_mcp/server.

# Understanding Responses

> This guide explains how CrissCross APIs indicate success and failure, and how to interpret response bodies.

### Overview

When you make API calls to CrissCross (Collect, Exchange, or Payouts), success and failure are indicated by **HTTP status codes** in the response header. The response body structure varies by endpoint. This guide explains how to interpret responses and handle errors in line with our standard REST API behaviour.

### Success vs failure: HTTP status codes

CrissCross follows standard REST conventions. **Do not** rely on a `status` field in the response body to determine success or failure. Instead, use the **HTTP status code** in the response header:

| Status code range                      | Meaning                                                            |
| -------------------------------------- | ------------------------------------------------------------------ |
| **2xx** (e.g. 200, 201, 202)           | Success. The request was accepted and processed as intended.       |
| **4xx** (e.g. 400, 401, 403, 404, 422) | Client error. The request was invalid, unauthorized, or not found. |
| **5xx** (e.g. 500, 503)                | Server error. Something went wrong on CrissCross’s side.           |

* **Success:** Use the status code (e.g. `200 OK`, `201 Created`, `202 Accepted`) to confirm success. The response body contains the resource or result as defined for that endpoint (no standard `"status": "success"` wrapper).
* **Failure:** Use the status code to detect failure. The body typically contains an `error` object with details (see [Error responses](#error-responses) below).

### Success responses

On success (2xx), the response body is **endpoint-specific**. There is no global wrapper with `"status": "success"`. The body is the resource or payload described in the API reference for that operation (e.g. a payout object, a list of transactions, a session).

Example pattern for a successful response (actual fields depend on the endpoint):

```json
{
  "id": "payout_abc123",
  "status": "PENDING",
  "merchantReference": "PAYOUT-001",
  "createdAt": "2024-01-15T10:30:00Z"
}
```

Always refer to the [API reference](/api-reference) for the exact success response schema of each endpoint.

### Error responses

On error (4xx or 5xx), the response body shape depends on which service you called. There are three distinct shapes — see the [Error Codes reference](/error-codes) for the full breakdown.

**Authentication** (`/auth/oauth2/token`) follows the OAuth 2.0 standard ([RFC 6749 §5.2](https://www.rfc-editor.org/rfc/rfc6749#section-5.2)):

```json
{
  "error": "invalid_client",
  "error_description": "Client authentication failed."
}
```

**Collect, Payouts, and related services** (Verification, Reporting, Settlement, Payers) return a flat envelope:

```json
{
  "message": "Phone number is required when pre-filled by merchant",
  "error": "Bad Request",
  "statusCode": 400
}
```

* **message** — Human-readable description.
* **error** — The error category, typically the HTTP reason phrase.
* **statusCode** — The HTTP status code, mirroring the response header.

**Exchange** returns a structured envelope with a stable, machine-readable `code`:

```json
{
  "error": {
    "code": "QUOTE_EXPIRED",
    "message": "Quote qut_550e8400-e29b-41d4-a716-446655440000 expired at 2026-04-21T14:00:00Z",
    "details": {
      "quoteId": "qut_550e8400-e29b-41d4-a716-446655440000",
      "expiredAt": "2026-04-21T14:00:00Z"
    }
  }
}
```

* **error.code** — Machine-readable identifier (e.g. `QUOTE_EXPIRED`, `INSUFFICIENT_BALANCE`). Branch on this.
* **error.message** — Human-readable description.
* **error.details** — Structured context whose shape depends on the code.

For the full list of codes per service and the recommended handling pattern for each shape, see the [Error Codes reference](/error-codes).

### Handling errors

1. **Use the HTTP status code** — Treat 2xx as success and 4xx/5xx as failure. Do not depend on a `status` field in the body.
2. **Parse the error body when present** — The shape differs per service. Collect and Payouts return the flat envelope, so read `body.message` for the human-readable detail and `body.error` for the category or machine-readable code. Exchange returns a structured envelope, so read `error.code` and `error.message` there.
3. **Log errors** — Log status code and error body for debugging and support.
4. **Retry wisely** — Implement retries only for appropriate cases (e.g. 429 Too Many Requests, 503 Service Unavailable) with backoff. Do not retry 4xx client errors blindly.

### Service-specific response patterns

Response **bodies** vary by service and endpoint:

* **Collect** — Payment status, transaction IDs, session data, etc., as per the Collect API reference.
* **Exchange** — Balances, rates, order and payout history, etc., as per the Exchange API reference.
* **Payouts** — Payout or batch details, status, references, etc., as per the Payouts API reference.

In all cases, **success vs failure is determined by the HTTP status code**, not by a field in the body.

### Tips for success

* **Check the status code first** — Use the response HTTP status (2xx vs 4xx/5xx) to decide whether the call succeeded.
* **Validate response bodies** — Ensure the success body matches what your integration expects; refer to the API reference for each endpoint.
* **Use the API reference** — Each endpoint documents its success and error response schemas.
* **Use SDKs when available** — CrissCross SDKs typically map status codes and error bodies for you.