Skip to main content

​
Hyperrial API Response Codes

Hyperrial uses standard HTTP response codes to communicate the outcome of API requests. Always inspect both the HTTP status code and the response body to fully understand what happened.

​
Success (2xx)

  • 200 OK
    The request was processed successfully.
    ⚠️ Always inspect the response payload to confirm the actual transaction state.
  • 201 Created
    A new resource was successfully created (e.g., transactions, accounts, or configurations).

​
Client Errors (4xx)

  • 400 Bad Request
    The request is malformed or missing required parameters.
    ✔️ Validate request payloads and data types.
  • 401 Unauthorized
    Authentication failed due to a missing or invalid API key.
    ✔️ Ensure your API key is included in the Authorization header.
  • 403 Forbidden
    The API key does not have permission to perform the requested action.
    ✔️ Verify the key’s scope or assigned role.
  • 404 Not Found
    The requested resource does not exist or the endpoint is incorrect.
  • 429 Too Many Requests
    Rate limit exceeded.
    ✔️ Implement retry logic with exponential backoff.

​
Server Errors (5xx)

  • 500, 502, 503, 504
    These indicate internal server errors on Hyperrial’s infrastructure.
    ✔️ Treat the outcome as inconclusive and retry later.
    ✔️ If persistent, contact support.

​
Error Handling Best Practices

Beyond HTTP status codes, Hyperrial responses may include structured error objects with additional context such as error type, message, and resolution hints.

​
General Guidelines

  • Do Not Assume Outcomes
    Network or timeout errors may leave the transaction state unknown.
  • Rely on Webhooks
    Webhooks provide authoritative confirmation of transaction outcomes and should be treated as the source of truth.

​
Common Error Types

Error TypeDescriptionRecommended Action
Invalid Request ErrorRequest parameters are invalid, missing, or incorrectly formatted.Review endpoint documentation and fix request payloads.
Authentication ErrorAPI key is missing, invalid, or inactive.Verify the API key and authorization headers.
Permission ErrorAPI key lacks the required permissions.Use a key with appropriate access or update role permissions.
Rate Limit ErrorToo many requests sent within a short timeframe.Implement retries with backoff or request higher limits.
Connection ErrorTemporary network or connectivity issue.Retry safely and rely on webhooks for final status.
Server ErrorInternal error on Hyperrial’s side.Retry later and monitor webhook events.
By properly handling these errors and relying on webhooks for final state confirmation, you can build resilient, fault-tolerant integrations with the Hyperrial API.