Skip to main content

​
Error Format

Every error response has the same shape: 
{"error": "human-readable message"}

​
Status Codes

CodeNameDescription
400Validation ErrorBad input — message is specific (e.g., "name is required")
401Authentication ErrorInvalid or missing API key / access token
402Insufficient BalanceBalance too low for the query — includes extra fields
403ForbiddenWrong role or not authorized
404Not FoundResource doesn’t exist
409ConflictDuplicate resource
500Server ErrorInternal error (generic message)

​
402 Insufficient Balance

The 402 response includes your current balance and the estimated cost: 
{
  "error": "insufficient balance",
  "balance": "0.50000000",
  "estimated_cost": "1.00000000"
}

​
Handling Errors

from datagate import (
    DatagateError,
    AuthenticationError,
    InsufficientBalanceError,
    ValidationError,
)

try:
    response = await client.query(text="...", dataset_ids=["..."])
except InsufficientBalanceError as e:
    print(f"Need ${e.estimated_cost}, have ${e.balance}")
except AuthenticationError:
    print("Check your API key")
except ValidationError as e:
    print(f"Bad request: {e.message}")
except DatagateError as e:
    print(f"Error {e.status_code}: {e.message}")