Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests.

HTTP Status Codes

Code	Name	Description
200	OK	Request succeeded. Response body contains the requested data.
201	Created	Resource created successfully. No response body.
204	No Content	Request succeeded. No response body (used for updates and deletes).
400	Bad Request	Invalid request. Missing required fields, validation errors, or malformed input.
401	Unauthorized	Missing or invalid authentication token.
403	Forbidden	Valid token, but insufficient permissions or node hierarchy violation.
404	Not Found	The requested resource does not exist or has been deleted.
409	Conflict	Action conflicts with the current state (e.g., duplicate approval, resource already exists).
413	Payload Too Large	Uploaded file exceeds the maximum allowed size (100 MB for documents).
500	Internal Server Error	An unexpected error occurred on the server.

Error Response Format

Domain Errors

Most error responses return a JSON object with code, domain, and message fields:

{
  "code": 30001,
  "domain": 3,
  "message": "account not found"
}

Field	Type	Description
code	integer	Application-specific error code
domain	integer	Error domain/category identifier
message	string	Human-readable error description

Validation Errors

When request body validation fails (400), the response returns an array of validation error objects:

[
  {
    "field": "Name",
    "message": "Validation failed on the 'required' tag"
  },
  {
    "field": "Type",
    "message": "Validation failed on the 'oneof' tag"
  }
]

Field	Type	Description
field	string	The field that failed validation
message	string	Description of the validation failure

Authentication Errors

Status	Scenario
401	No Authorization header provided
401	Token is expired
401	Token signature is invalid
401	API key is expired or inactive

Authorization Errors

Status	Scenario
403	API key's node cannot manage the target resource
403	Insufficient role priority for the requested action
403	Missing required permission (e.g., document:upload)

Best Practices

1. Check the status code first -- different status codes require different handling strategies.
2. Read the error message -- it provides specific details about what went wrong.
3. Implement retry logic for 500 errors with exponential backoff.
4. Do not retry 400, 401, 403, 404, or 409 errors -- these require changes to the request.
5. Refresh tokens proactively before they expire to avoid 401 errors during operations.