Responses

Overview

The Oquira API follows consistent response conventions across all endpoints. Understanding these patterns will help you integrate more efficiently.

Success Responses

All successful responses include a success flag set to true and a data payload containing the requested information.

Single Resource

When fetching a single resource:

{
  "success": true,
  "data": {
    "id": "srv_7k92m1",
    "name": "Customer Service",
    "status": "active",
    "createdAt": "2024-01-15T08:00:00Z",
    "updatedAt": "2024-03-20T10:00:00Z"
  }
}

List of Resources

When fetching multiple resources, the response includes pagination metadata:

{
  "success": true,
  "data": [
    { "id": "srv_7k92m1", "name": "Customer Service" },
    { "id": "srv_8n3p5q", "name": "Technical Support" }
  ],
  "meta": {
    "total": 45,
    "page": 1,
    "limit": 10,
    "hasMore": true
  }
}

Empty Lists

When no resources match the query:

{
  "success": true,
  "data": [],
  "meta": {
    "total": 0,
    "page": 1,
    "limit": 10,
    "hasMore": false
  }
}

Pagination

For list endpoints, use these query parameters to paginate:

Example

curl -X GET "https://api.oquira.com/v1/business/services?page=2&limit=20" \
  -H "X-API-Key: your_api_key_here"

Response Metadata

Error Responses

When an error occurs, the response includes success: false and an error object with details:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is invalid",
    "details": {
      "field": "email",
      "reason": "Must be a valid email address"
    },
    "timestamp": "2024-03-20T10:00:00.000Z",
    "requestId": "req_5f2b8c9d1e"
  }
}

Error Object Fields

Request Tracking

Every API request is assigned a unique requestId. This identifier is included in:

• All response bodies (both success and error)
• The X-Request-ID response header

Custom Request IDs

You can provide your own request ID to track requests across your systems:

curl -X GET "https://api.oquira.com/v1/business/services" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-Request-ID: your-custom-request-id-123"

The API will echo your ID back in the response and logs, making it easier to correlate requests.

Tip: Always log the requestId when making API calls. It helps our support team diagnose issues quickly.

Common Response Headers

All API responses include these headers:

Timestamps

All timestamps in the API follow the ISO 8601 format in UTC:

2024-03-20T10:30:00.000Z

When sending dates in requests:

• ISO 8601 format is preferred: 2024-03-20T10:30:00Z
• Date-only format is accepted where applicable: 2024-03-20

Null Values

• Null fields may be omitted from responses to reduce payload size
• When updating resources, sending null explicitly will clear the field
• Arrays will always be present as empty [] rather than null

Next Steps

• Errors - Complete list of error codes
• Rate Limits - API usage limits and headers
• Getting Started - Make your first API call