Error Handling

The Gestix API uses standard HTTP status codes and returns structured error objects on failures.

---

HTTP Status Codes

Code	Meaning	When it occurs
200	OK	Successful GET request
201	Created	Successful POST or PUT request
400	Bad Request	Missing or invalid parameters or request body
403	Forbidden	Invalid, expired, or missing session token
409	Conflict	Duplicate entry (e.g., document or entity already exists)

---

Error Response Format

All 400 and 409 responses return an apiError object:

{
  "code": "INVALID_ARGUMENT",
  "message": "Field 'currency' is required",
  "timestamp": "2024-11-15T10:30:00Z",
  "path": "/invoices",
  "request_id": "req-abc123"
}

Field	Type	Description
code	string	Stable machine-readable error code
message	string	Human-readable description
timestamp	string	When the error occurred (ISO 8601)
path	string	Request path (optional)
request_id	string	Server-generated trace ID (optional)

---

Common Error Codes

code	Description
INVALID_ARGUMENT	A required field is missing or a value is out of range
AUTH_FAILED	Authentication failed (wrong API token or credentials)
DB_TIMEOUT	Database timeout — retry after a short delay
DUPLICATE_ENTRY	A record with the same unique key already exists

---

Handling Errors in Code

Python example

import requests

response = requests.post(
    f"{BASE_URL}/invoices",
    params={"nonce": nonce},
    headers={"Authorization": f"Bearer {token}"},
    json=document_data
)

if response.status_code == 201:
    result = response.json()
    print(f"Created: {result['documentNumber']}")
elif response.status_code == 400:
    error = response.json()
    print(f"Error {error['code']}: {error['message']}")
elif response.status_code == 409:
    print("Duplicate document — already exists")
elif response.status_code == 403:
    print("Session expired — re-authenticating...")
    token = get_session_token(api_token)
    # retry...

JavaScript example

const response = await fetch(`${BASE_URL}/invoices?nonce=${nonce}`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(documentData)
});

if (!response.ok) {
  const error = await response.json();
  console.error(`API Error [${error.code}]: ${error.message}`);
}

---

403 — Session Expiry

A 403 response means your session token has expired or is invalid. Re-authenticate by calling GET /helo again to get a new xa-token.

Proactive health checks

Use GET /status to check session health and inspect any recent errors before making write operations.

---

Support

If an error persists, note the request_id and timestamp from the error response and contact support@gestix.com — these values help trace the issue in server logs.