API Response Patterns

Ownera's Transactional API exposes endpoints that trigger operations spanning multiple nodes in the FinP2P network. These operations may be long-running with execution times ranging from milliseconds to minutes, and are outside the control of your organization's FinP2P node.

To accommodate these cases, the Transactional API provides operation semantics that allow API clients to safely invoke endpoints and handle long-running operations robustly, including recovery from potential failures. Endpoints that represent potential long-running operations return HTTP status code 202 along with metadata about the operation execution, including the operation completion status (isCompleted) and a correlation id (cid) that serves as a unique identifier for the underlying operation execution.

Response Types

Synchronous Operations

Operations that complete immediately return HTTP status 200 with the result:

{
  "id": "<string>"
}

These operations never require polling and represent the final outcome.

Asynchronous Operations

When an operation is initiated but cannot complete immediately, the API returns HTTP status 202 with tracking information:

{
  "cid": "<correlationId>",
  "isCompleted": false
}

When isCompleted is false, you must poll the operation status using the Get Operation Status endpoint with the provided cid. Continue polling until isCompleted becomes true.

Polling responses return HTTP status 200 with one of these formats:

Operation completed successfully:

{
  "cid": "<correlationId>",
  "isCompleted": true,
  "type": "<operationType>",
  "response": {
    "type": "<string>",
    "id": "<string>"
  }
}

Note: The id value in the response object represents the same id that would be returned directly by a synchronous operation. The id itself is identical regardless of whether the operation completes synchronously or asynchronously.

Operation completed with errors:

{
  "cid": "<correlationId>",
  "isCompleted": true,
  "type": "<operationType>",
  "response": {
    "type": "error",
    "errors": [
      {
        "code": "<int>",
        "message": "<string>"
      }
    ]
  }
}

Immediate Error Responses

When input validation, business logic validation, or server errors occur, the API immediately returns an error response with HTTP status 4XX (client errors) or 5XX (server errors):

{
  "type": "error",
  "errors": [
    {
      "code": "<int>",
      "message": "<string>"
    }
  ]
}

The errors array supports multiple error objects in a single response. Each error includes an Ownera-specific error code and descriptive message. All error codes are documented in theAPI Error Codes Reference.

Important Notes

• Both input validation and business logic errors use the same standardized error structure
• The errors array always supports multiple errors per request
• Asynchronous operations may complete successfully or with errors - always check the response.type field
• All error codes are Ownera-defined and documented in the API Error Codes Reference
• For asynchronous operations, when isCompleted is false, polling on the operation status endpoint using the given cid continues until isCompleted is true and the outcome is presented in the response field
• 400 errors are final - do not retry the original request
• Synchronous operations never require polling

Idempotency

All mutating endpoints (POST, PUT, PATCH) require an Idempotency-Key header to ensure safe retries. If a request fails due to network issues or timeouts, you can safely retry with the same idempotency key — the Router will return the original response rather than executing the operation twice.

Header Format

Idempotency-Key: <32-byte hex string>

The key is a 32-byte buffer encoded as hex (64 characters), composed of:

• 24 random bytes — ensures uniqueness
• 8 bytes — epoch timestamp in seconds

Behavior

When you retry a request with the same idempotency key, the Router returns the cached response from the original request rather than executing the operation again.

If you reuse an idempotency key with a different request body, the API returns 409 Conflict. Generate a new key if this is a different operation, or use the original request body if retrying.

Best Practices

• Generate a new key for each distinct operation — Don't reuse keys across different logical operations
• Persist the key before sending — Store the idempotency key so you can retry after crashes
• Use the same key for retries only — Retrying with a different key will create a duplicate operation