Request and response conventions

Use JSON for JSON endpoints and the endpoint’s upload form for binary import sources. Each endpoint validates its own fields; this page describes shared conventions, not a universal request-body schema.

Successful responses

JSON responses wrap the endpoint result in data:

{ "data": { "example": true } }

The object above is illustrative. Use the actual endpoint’s result shape. Collections can also include pagination metadata; inspect it before treating a list as complete.

Error responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "A safe explanation",
    "requestId": "a-request-uuid"
  }
}

Keep the safe code, HTTP status and request identifier for diagnostics. Provider implementation text is not a stable public schema.

IDs, dates and currencies

Resource IDs refer to owned records. Read them from the authenticated user’s API rather than copying another account’s ID.

User-day dates use Africa/Cairo semantics. A financial amount needs its currency and date or period. A reference exchange rate also needs its currency pair and observation time.

Unknown fields, malformed values and unsupported methods can be refused. Fix the supplied field error before retrying the same action.

Client behavior

Set finite timeouts, parse the envelope after checking the HTTP result, and preserve unavailable states. Do not log complete financial payloads or authorization headers. Continue with client integration, errors and pagination.