Error Handling

The API uses consistent error responses across all endpoints with structured error objects and trace IDs.

Error Response Format

{
  "success": false,
  "error": {
    "message": "Invalid credentials",
    "statusCode": 401,
    "details": {}
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Every error response includes a requestId for debugging and support.

Status Codes

Validation Errors

When request validation fails, the details field contains specific field errors:

{
  "success": false,
  "error": {
    "message": "Validation error",
    "statusCode": 400,
    "details": {
      "fieldErrors": {
        "metrics": ["Required"]
      },
      "formErrors": []
    }
  }
}

Retry Strategy

For transient errors (429, 500, 502), implement exponential backoff:

1. Wait 1 second, then retry
2. Wait 2 seconds, then retry
3. Wait 4 seconds, then retry
4. Give up after 3 retries

The API itself handles per-integration rate limiting with adaptive backoff, but your client should also handle rate limits at the API level.

Integration-Specific Errors

When an upstream API returns an error, the API wraps it in a consistent format:

{
  "success": false,
  "error": {
    "message": "Upstream API error: Rate limit exceeded",
    "statusCode": 502
  }
}

Testing Connections

Always test credentials before running queries to catch auth issues early:

curl -X POST https://api.oviond.com/v1/integrations/{id}/test \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": { "apiKey": "YOUR_API_KEY" }
  }'

A 200 response with status: 200 means the credentials are valid.