Understanding Responses

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:

• 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 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):

1
{
2
  "id": "payout_abc123",
3
  "status": "PENDING",
4
  "merchantReference": "PAYOUT-001",
5
  "createdAt": "2024-01-15T10:30:00Z"
6
}

Always refer to the API reference for the exact success response schema of each endpoint.

Error responses

On error (4xx or 5xx), the response body usually includes an error object with a code and message:

1
{
2
  "error": {
3
    "code": "INVALID_REQUEST",
4
    "message": "Invalid API Key"
5
  }
6
}

• code — Machine-readable code for programmatic handling (e.g. UNAUTHORIZED, VALIDATION_ERROR, INSUFFICIENT_BALANCE).
• message — Human-readable description of the error.

The exact shape may vary slightly by service; check the API reference for that endpoint.

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 — For 4xx/5xx, read the error object (e.g. error.code, error.message) for details and user-facing messages.
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.