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