Error Handling

The Trade Hub API uses standard HTTP status codes to indicate the success or failure of a request. Codes in the 2xx range indicate success, 4xx codes indicate a client error, and 5xx codes indicate a server error.

Error response format

All errors return a JSON body with a detail field describing the problem:

{
  "detail": "Error description"
}

For validation errors (422), the format includes additional details:

{
  "detail": [
    {
      "loc": ["body", "content"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Error codes

401 Unauthorized

Invalid or missing API key. Verify that the X-API-Key header is present and contains a valid key.

{
  "detail": "Invalid or missing API key"
}

Common causes:

• X-API-Key header missing from the request
• API key expired or revoked
• Key copied with extra spaces or characters
• API key deactivated by an organization administrator

Resolution:

• Verify the header is correctly spelled (X-API-Key, not X-Api-Key)
• Check that the key is active in the developer dashboard
• Regenerate the key if needed

402 Payment Required

Insufficient credit balance or spending limit reached. Your organization has run out of credits or has reached its monthly spending limit.

{
  "detail": "insufficient balance"
}

Common causes:

• Prepaid credit balance exhausted (balance mode)
• Monthly spending limit reached (invoice mode)

Additional headers:

• X-Balance-Cents: current balance in cents (balance mode)
• X-Spending-Limit / X-Spending-Current: limit and current spending (invoice mode)

Resolution:

• Top up your credit balance from the billing dashboard
• Adjust your spending limit if needed
• Enable auto-recharge to avoid interruptions

403 Forbidden

Insufficient permissions. Your API key does not have the required rights for this operation.

{
  "detail": "Insufficient permissions for this operation"
}

Common causes:

• Attempting to access a resource from another organization
• API key with restricted permissions
• API key scope insufficient for this resource

Resolution:

• Verify the resource belongs to your organization
• Contact your organization administrator to adjust permissions

404 Not Found

Resource not found. The specified identifier does not match any existing resource.

{
  "detail": "Job not found"
}

Common causes:

• Incorrect job or batch identifier
• Resource deleted
• Identifier from another organization

Resolution:

• Check the identifier in your request
• Use the history endpoint to find the correct resource

422 Unprocessable Entity

Validation error. The request body does not match the expected format.

{
  "detail": [
    {
      "loc": ["body", "content"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Common causes:

• Required field missing (content)
• Incorrect data type (string instead of array)
• Value outside accepted limits
• Invalid JSON format in the request body

Resolution:

• Check the endpoint documentation for required parameters
• Validate your JSON before sending
• Verify data types for each field

429 Too Many Requests

Rate limit exceeded. You have sent too many requests within the time window.

{
  "detail": "Rate limit exceeded. Retry in 12 seconds."
}

Resolution:

• Wait for the duration specified in the Retry-After header
• Implement exponential backoff
• Use batch classification to reduce the number of requests

500 Internal Server Error

Internal server error. An unexpected error occurred on the server side.

{
  "detail": "Internal server error"
}

Resolution:

• Retry the request after a few seconds
• If the error persists, contact support with the request identifier
• Check the status page for ongoing incidents

503 Service Unavailable

Service temporarily unavailable. The service is under maintenance or overloaded.

{
  "detail": "Service temporarily unavailable. Please try again later."
}

Resolution:

• Retry after a few minutes
• Check the status page for planned maintenance
• Implement a queue mechanism for failed requests

Summary table

Recommended handling

import httpx

client = httpx.Client(
    base_url="https://api.thetradehub.eu",
    headers={"X-API-Key": "th_live_your_api_key"},
)

response = client.post("/v1/classify/jobs", json={
    "content": "Wireless Bluetooth headphones"
})

match response.status_code:
    case 201:
        job = response.json()
        print(f"Job created: {job['id']}")
    case 401:
        print("Authentication error. Check your API key.")
    case 402:
        print("Insufficient balance. Top up your credits.")
    case 422:
        errors = response.json()["detail"]
        for error in errors:
            print(f"Validation: {error['loc']} - {error['msg']}")
    case 429:
        retry_after = int(response.headers.get("Retry-After", 10))
        print(f"Rate limited. Retry in {retry_after}s.")
    case code if code >= 500:
        print(f"Server error ({code}). Retry later.")
    case _:
        print(f"Unexpected error: {response.status_code}")

const response = await fetch("https://api.thetradehub.eu/v1/classify/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": "th_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ content: "Wireless Bluetooth headphones" }),
});

switch (response.status) {
  case 201: {
    const job = await response.json();
    console.log(`Job created: ${job.id}`);
    break;
  }
  case 401:
    console.error("Authentication error. Check your API key.");
    break;
  case 402:
    console.error("Insufficient balance. Top up your credits.");
    break;
  case 422: {
    const { detail } = await response.json();
    for (const error of detail) {
      console.error(`Validation: ${error.loc.join(".")} - ${error.msg}`);
    }
    break;
  }
  case 429: {
    const retryAfter = response.headers.get("Retry-After") || "10";
    console.warn(`Rate limited. Retry in ${retryAfter}s.`);
    break;
  }
  default:
    if (response.status >= 500) {
      console.error(`Server error (${response.status}). Retry later.`);
    } else {
      console.error(`Unexpected error: ${response.status}`);
    }
}