Errors

Overview

When something goes wrong with an API request, Oquira returns a structured error response that helps you identify and resolve the issue.

HTTP Status Codes

Oquira uses standard HTTP response codes to indicate the success or failure of an API request.

Success Codes

Client Error Codes

Server Error Codes

Error Response Format

All error responses follow this structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable explanation of what went wrong",
    "details": {
      "field": "Which field caused the error",
      "reason": "Why it failed"
    },
    "timestamp": "2024-03-20T10:00:00.000Z",
    "requestId": "req_5f2b8c9d1e"
  }
}

Error Codes Reference

Authentication Errors

Authorization Errors

Validation Errors

Resource Errors

Rate Limiting Errors

Queue and Ticket Errors

Subscription Errors

Validation Error Details

For VALIDATION_ERROR, the details object provides specific information about what failed:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed for 2 fields",
    "details": {
      "errors": [
        {
          "field": "email",
          "message": "Must be a valid email address",
          "received": "invalid-email"
        },
        {
          "field": "phone",
          "message": "Must match format: +1234567890",
          "received": "123"
        }
      ]
    },
    "timestamp": "2024-03-20T10:00:00.000Z",
    "requestId": "req_5f2b8c9d1e"
  }
}

Troubleshooting Guide

1. Check the Error Message

The message field provides a human-readable explanation. Start here to understand what went wrong.

2. Inspect the Details

For validation errors, the details object tells you exactly which fields failed and why.

3. Review Your Request

Common issues to check:

• Is the JSON properly formatted?
• Are all required fields present?
• Are field values the correct type?
• Is your API key included in the headers?

4. Check Rate Limits

If you receive a 429 error:

• Check the Retry-After header for when to retry
• Review your usage patterns in the dashboard
• Consider implementing request queuing

5. Note the Request ID

Always log the requestId from error responses. When contacting support, provide:

• The requestId
• The endpoint URL you called
• The approximate time of the error
• A description of what you were trying to do

Contact Support

If you can't resolve an issue:

1. Log the requestId and error details
2. Check our status page for any ongoing incidents
3. Email support@oquira.com with:
   • Your requestId
   • The endpoint and method you tried
   • Your request body (with sensitive data redacted)
   • Steps to reproduce the issue

Next Steps

• Rate Limits - Understand API usage limits
• Responses - Learn about response formats
• Authentication - Review authentication methods