Error Handling

The Gesvision API uses standard HTTP status codes and returns a consistent JSON error body for all error responses.

Error response format

Every error response follows this structure:

{
  "status": 404,
  "error": "NOT_FOUND",
  "message": "Invoice with id 99 not found"
}

Field	Type	Description
status	integer	HTTP status code (mirrors the response header)
error	string	Machine-readable error code for programmatic handling
message	string	Human-readable description of what went wrong

HTTP status codes

Success codes

Code	Meaning	Used by
200	OK	GET, PUT — resource returned successfully
201	Created	POST — resource created successfully
204	No Content	DELETE — resource deleted successfully

Client error codes

Code	Meaning	When it happens
400	Bad Request	Missing required fields, invalid values, validation errors
401	Unauthorized	Missing, expired, or invalid JWT token
404	Not Found	The requested resource does not exist
409	Conflict	Optimistic locking conflict — the resource was modified by another client (see Optimistic Locking)

Server error codes

Code	Meaning	When it happens
500	Internal Server Error	Unexpected server failure — contact Gesvision support if persistent

Error handling best practices

1. Always check the HTTP status code first

response = requests.get(f"{BASE_URL}/api/v1/invoices/999", headers=headers)

if response.status_code == 404:
    print("Invoice not found")
elif response.status_code == 401:
    token = refresh_token()  # re-authenticate
    # retry the request
elif response.status_code >= 500:
    log.error(f"Server error: {response.json()['message']}")

2. Handle 401 by re-authenticating

# If you get 401, request a new token
curl -X POST https://app.gesvision.com/Gesvision/rest/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "api_user", "password": "your_password"}'

3. Handle 409 by refetching and retrying

When you receive a 409 Conflict on an update or delete:

1. Re-fetch the resource to get the latest version
2. Merge your intended changes with the current state
3. Retry with the updated version in If-Match

4. Log full error bodies

Always log the complete error response for debugging — the message field often contains specific information about what validation failed or which related entity was not found.