Error Reference

This section outlines the standard error responses you may encounter when using the Orca API.

Error Response Format

Most API errors follow a consistent JSON structure:


{
  "error": {
    "type": "ERROR_TYPE",
    "message": "Human-readable error description (optional)",
    "details": ["Additional error details (optional)"]
  },
  "timestamp": 1755602195137
}

Exception: 401 Unauthorized is returned as a plain-text body, not in this envelope. See Authentication.

HTTP Status Codes

Status Code	Description
`400`	Bad Request - Invalid request format or validation failed
`401`	Unauthorized - Authentication required or invalid credentials
`403`	Forbidden - either the endpoint is not enabled for your client type, or access was denied by the Firewall - contact support if unexpected
`404`	Not Found - Resource not found
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Server-side error occurred

Error Types

VALIDATION_ERROR (400)

Request validation failed due to invalid or missing required fields.

In the case of failed validation, the details section will include information about the failed field/s with reason details, for example:


{
    "error": {
        "type": "VALIDATION_ERROR",
        "message": "Request validation failed",
        "details": [
            "/amount: Expected number to be greater or equal to 0"
        ]
    },
    "timestamp": 1755602195137
}

NOT_FOUND (404)

The referenced resource does not exist.


{
    "error": {
        "type": "NOT_FOUND",
        "message": "Transaction not found"
    },
    "timestamp": 1755602195137
}

SERVER_ERROR (500)

Internal server error occurred during request processing.


{
    "error": {
        "type": "SERVER_ERROR",
        "message": "Failed to process transaction"
    },
    "timestamp": 1755602195137
}