Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.oathnet.org/llms.txt

Use this file to discover all available pages before exploring further.

​
Error Response Format

Backend-generated errors generally use a consistent envelope, even when the successful response for that endpoint is raw JSON or a file stream: 
{
  "success": false,
  "message": "Human-readable error description",
  "errors": {
    "field_name": "Specific error details",
    "general": "General error information"
  }
}

​
HTTP Status Codes

CodeNameDescription
200OKRequest succeeded
202AcceptedAsync job was accepted or queued
400Bad RequestInvalid parameters or request body
401UnauthorizedMissing or invalid API key
403ForbiddenAccess denied or quota exceeded
404Not FoundResource does not exist or is not owned by the caller
409ConflictDownload requested before a job is ready
429Too Many RequestsRate limit or plan limit exceeded
500Internal Server ErrorServer-side error
502Bad GatewayUpstream service unavailable
503Service UnavailableTemporary maintenance or dependency outage
Do not assume every successful 2xx response includes a success field. Search endpoints and legacy lookups do, but job endpoints, autocomplete endpoints, manifests, scanner endpoints, and download endpoints may not.

​
Common Errors

​
400 Bad Request

{
  "success": false,
  "message": "Invalid request",
  "errors": {
    "q": ["This field is required."]
  }
}
Typical causes:
  • missing required parameters
  • invalid filter JSON
  • filter nesting deeper than 2 levels
  • more than 50 filter leaf conditions
  • unsupported filter operator or field for that endpoint
  • wildcard-like patterns that are too short
  • unsupported scanner query_config keys
  • malformed filter_id

​
401 Unauthorized

{
  "success": false,
  "message": "Invalid API key."
}
Typical causes:
  • missing x-api-key
  • revoked or invalid key

​
403 Forbidden

Typical causes:
  • daily lookup quota exhausted
  • endpoint requires a higher plan
  • scanner quota exhausted
  • file search, exports, bulk search, or AI filter not enabled on the current plan

​
404 Not Found

Typical causes:
  • unknown log_id, file_id, job_id, scanner_uid, or run_uid
  • job or scanner exists but is not owned by the authenticated caller

​
429 Too Many Requests

Typical causes:
  • endpoint rate limit exceeded
  • daily bulk-search limit reached
  • scanner creation or test-delivery rate limits hit

​
Implementation Pattern

When writing a client:
  1. trust HTTP status first
  2. parse JSON when the endpoint is documented as JSON
  3. only inspect success when the payload actually includes it
  4. treat download endpoints as raw text or binary streams

​
Example Client Logic

import requests

class OathNetError(Exception):
    def __init__(self, message: str, status_code: int, errors: dict | None = None):
        super().__init__(message)
        self.status_code = status_code
        self.errors = errors or {}


def handle_json_response(response: requests.Response) -> dict:
    payload = response.json()

    if response.status_code >= 400:
        raise OathNetError(
            payload.get("message", "Request failed"),
            response.status_code,
            payload.get("errors"),
        )

    if "success" in payload and not payload["success"]:
        raise OathNetError(
            payload.get("message", "Request failed"),
            response.status_code,
            payload.get("errors"),
        )

    return payload