Errors

The TraxServer v5 API uses two distinct error mechanisms depending on the nature of the failure.

HTTP Status Codes

Errors at the transport or authentication layer return a non-2xx HTTP status code:

Status	Meaning	Description
200	OK	Request succeeded, or a business-logic validation failure occurred (check `result` in the body)
400	Bad Request	Malformed request, invalid JSON, or an unacceptable argument
401	Unauthorized	Missing or invalid session token
403	Forbidden	Valid session but insufficient permissions for this operation
500	Server Error	An unexpected internal error occurred

HTTP Error Response

Non-2xx responses return a simple JSON object:

{
  "error": "Session token is invalid or has expired."
}

Business Logic Errors (HTTP 200)

Validation and business rule failures return HTTP 200 with a result of "FAILURE" in the response body. Always check the result field: a 200 does not guarantee success.

Response Schema

string

"SUCCESS" or "FAILURE"

number | null

The ID of the created or updated resource, if applicable

object | null

Additional data returned by the operation

object | null

Present when result is "FAILURE" (see below)

Error Object Schema

object

Map of field name to error. Each value has type and errorMessage.

array

List of errors not tied to a specific field. Each item has type and errorMessage.

Error Types

Type	Description
`REQUIRED`	A required field was missing or blank
`DUPLICATE`	The value conflicts with an existing record
`INVALID_VALUE`	The value is present but not acceptable
`INVALID_FORMAT`	The value is not in the expected format
`INVALID_MAPPING`	The value does not map to a known resource
`NOT_MODIFIABLE`	The field cannot be changed in its current state
`DELETE`	The resource cannot be deleted due to existing dependencies
`GENERAL`	A non-field-specific validation failure

Example: Field Validation Failure

{
  "result": "FAILURE",
  "id": null,
  "dataObject": null,
  "errors": {
    "fieldErrors": {
      "amount": {
        "type": "REQUIRED",
        "errorMessage": "Amount is required."
      },
      "date": {
        "type": "INVALID_FORMAT",
        "errorMessage": "Date must be in YYYY-MM-DD format."
      }
    },
    "globalErrors": []
  }
}

Example: Global Error

{
  "result": "FAILURE",
  "id": null,
  "dataObject": null,
  "errors": {
    "fieldErrors": {},
    "globalErrors": [
      {
        "type": "GENERAL",
        "errorMessage": "This transaction has already been reconciled and cannot be modified."
      }
    ]
  }
}

Recommendations

Always check the result field on 200 responses before treating an operation as successful.
Use fieldErrors to surface inline validation messages to users.
Use globalErrors for form-level or operation-level error banners.
Log the full error response for troubleshooting: type is machine-readable and suitable for programmatic handling.

Getting Started

Products

International Support

HTTP Status Codes

HTTP Error Response

Business Logic Errors (HTTP 200)

Response Schema

Error Object Schema

Error Types

Example: Field Validation Failure

Example: Global Error

Recommendations

​HTTP Status Codes

​HTTP Error Response

​Business Logic Errors (HTTP 200)

​Response Schema

​Error Object Schema

​Error Types

​Example: Field Validation Failure

​Example: Global Error

​Recommendations

HTTP Status Codes

HTTP Error Response

Business Logic Errors (HTTP 200)

Response Schema

Error Object Schema

Error Types

Example: Field Validation Failure

Example: Global Error

Recommendations