Error Handling Standards

​

Overview

The OFAuth API uses standard HTTP status codes with structured JSON error responses to provide clear, actionable feedback when things go wrong. This systematic approach helps developers quickly identify and resolve issues.

​

Error Response Format

All API errors return a consistent JSON structure with three core fields:

• error: a human-readable description of what went wrong
• code: a machine-readable identifier you can branch on in your client
• details: optional contextual information such as the affected field

​

Error Response Fields

​

HTTP Status Codes

​

Success Codes

​

Client Error Codes

​

Server Error Codes

​

Error Code Categories

​

Authentication Errors (AUTH_*)

​

Validation Errors (VALIDATION_*)

​

Rate Limiting Errors (RATE_LIMIT_*)

​

Connection Errors (CONNECTION_*)

​

Upstream Errors (UPSTREAM_*)

​

Dynamic Rules Errors (RULES_*)

​

Error Handling Examples

​

Basic Error Handling

Follow these practices when calling the API from client code:

• Check response.ok before parsing the body and surface the HTTP status in your logs.
• Parse the JSON payload and branch on errorData.code to determine the recovery path.
• Redirect users to re-authentication when you receive connection or session errors.
• Respect the X-RateLimit-Retry-After header and pause before retrying rate-limited calls.
• Bubble up unexpected errors so they can be reported to your monitoring stack.

​

Advanced Error Handler Class

Build a reusable error-handling helper so every request is treated consistently. The helper should:

• Centralize logging of HTTP status codes, request identifiers, and the parsed error payload.
• Categorize errors (retryable, authentication, validation) to route them to the right recovery logic.
• Apply backoff to retryable errors and honour server-provided retry hints.
• Trigger re-authentication flows when connection or session errors are detected.
• Raise typed exceptions (for example ApiError, AuthError, ValidationError) so downstream code can react precisely.

​

Validation Error Details

Validation errors include specific field information. Expect details.field to identify the problematic input, details.message to describe the issue, and details.value (when provided) to show what was rejected. Handle validation errors with user-friendly messages by mapping the fields in details to UI controls, highlighting the inputs that need attention, and surfacing the descriptive message inline for the user.

​

Debugging Tips

​

Error Monitoring

Implement error tracking for production applications by storing structured error metadata, tracking frequency per error code, sending alerts when thresholds are exceeded, and forwarding enriched events (timestamp, status, stack trace, and request context) to your monitoring platform.

​

Common Error Scenarios

​

Authentication Issues

When you receive authentication or connection errors:

• Inspect the response body for CONNECTION_EXPIRED, AUTH_SESSION_EXPIRED, or related codes.
• Inform the user that they must reconnect and send them through the hosted re-authentication flow.
• Clear cached credentials so the next attempt starts with a fresh session.
• Log the status, code, and affected connection ID for support follow-up.

​

Rate Limiting

Handle rate limits by adopting exponential backoff. Read the X-RateLimit-Retry-After header (it defaults to 60 seconds when missing), pause before the next attempt, and stop retrying once the maximum retry count has been reached. Track cumulative failures so you know when to surface a persistent outage to the user.

​

Next Steps