API Reference

Welcome to the ERPx API Reference. This documentation provides a structured collection of RESTful endpoints, organized to match the ERPx user interface for ease of navigation and familiarity.

Each section corresponds to a functional area in the ERPx and includes:

Index of available APIs within the area.
Endpoint details for querying, creating, updating, or deleting objects.
Data objects for querying.

Developers can use these APIs to automate and integrate ERPx processes, enabling seamless interaction with modules such as Accounting, Project management, Procurement, and more.

The structure and organization of this reference are designed to closely resemble the ERPx menus, making it intuitive for both technical and business users to locate and understand the available API documentation.

Handling API responses

Understanding and properly handling HTTP response codes are critical for building reliable integrations with ERPx APIs. Every response includes a status code that indicates whether your request succeeded or failed, and how to proceed.

Status code categories

Code Range	Category	Description
200-299	Success	Your request was successfully received, understood, and accepted.
300-399	Redirection	Additional action is required to complete the request.
400-499	Client Error	The request contains invalid syntax or cannot be fulfilled.
500-599	Server Error	The server encountered an error when processing a valid request.

Common status codes

Success responses

Code	Status	When it appears
200	OK	Request completed successfully.
201	Created	Resource is successfully created (POST requests).
202	Accepted	Request is accepted for processing.
204	No Content	Request is successful, no content to return.

Client error responses

Code	Status	When it appears	Action required
400	Bad Request	Validation errors or malformed request	Review request’s syntax and parameters.
401	Unauthorised	Missing or invalid authentication	Verify API credentials.
403	Forbidden	Authenticated but lacking permissions	Check user access rights.
404	Not Found	Resource or endpoint doesn’t exist	Verify URI and resource ID.
405	Method Not Allowed	HTTP method is not supported	Use the correct HTTP method (GET, POST, etc.).
409	Conflict	Concurrency or duplicate resource error	See Conflict Errors below.
413	Payload too large	Your request’s data is too big	See Limits & Quotas section.
422	Unprocessable Entity	Business logic validation failed	See Validation Errors below.
429	Too Many Requests	Rate limit exceeded	Implement backoff and retry logic.

Server error responses

Code	Status	When it appears	Action required
500	Internal Server Error	Unexpected server-side error	Retry request; contact support if persists.
503	Service Unavailable	Service temporarily unavailable	Implement retry with exponential backoff. See Limits & Quotas section.

Detailed error scenarios

409 Conflict errors

The 409 Conflict status indicates a concurrency or duplication issue:

Scenario 1: Concurrent updates

Another user modified or deleted the resource after you retrieved it but before you updated it.
Error Code: 3090

Scenario 2: Duplicate resource

This is an attempt to create a resource that already exists with the same unique identifiers.
Error Code: 3090

Example response:

{
  "code": "3090",
  "message": "Data has been changed or deleted by another user"
}

How to handle:

Retrieve the latest version of the resource.
Reapply your changes.
Retry the update with the current data.

404 Not Found errors

The 404 Not Found status occurs in two scenarios:

Invalid endpoint

The API endpoint URI doesn’t exist.

Error code: 1030

Example:

GET /v1/customers-does-not-exist/123456

{
  "code": "1030",
  "message": "No resource found matching request URI"
}

Resource doesn’t exist

The endpoint is valid, but the specific resource ID doesn’t exist.

Error code: 1040

Example:

GET /v1/customers/123456

{
  "code": "1040",
  "message": "Requested entity not found"
}

422 Validation errors

The 422 Unprocessable Entity status indicates business logic or validation failures. The response includes detailed error information embedded in the resource.

Error code: 3010 - Model validation error

Response structure:

Failed fields are highlighted in the response.
A notificationMessages object that contains detailed errors for each field appears.

Example:

PATCH /v1/customers/2245

Request Body:
[
  {
    "path": "/countryCode",
    "op": "Replace",
    "value": "ZZ"
  }
]

{
  "customerId": "2245",
  "customerName": "Demo Company AS",
  "aliasName": "DEMO",
  "companyId": "EN",
  "companyRegistrationNumber": "",
  "countryCode": "ZZ",
  "lastUpdated": {
    "updatedAt": "2015-10-20T13:00:24.000",
    "updatedBy": "SUPERUSER"
  },
  "notificationMessages": {
    "countryCode": [
      {
        "code": 3010,
        "message": "Illegal value."
      }
    ]
  }
}

How to handle:

Parse the notificationMessages object.
Identify which fields failed the validation.
Correct the invalid values.
Resubmit the request.

Error handling best practices

Do’s

Best practices for successful requests

Check the status codes before processing response data.
Validate inputs on client-side to reduce 400/422 validation errors.
Monitor rate-limit headers to proactively avoid 429 responses.

Robust error handling

Implement retry logic with exponential backoff for 429, 500, and 503 error responses.
Parse the error responses to extract error codes and messages.
Log errors with full context (request ID, endpoint, payload, timestamp).
Handle the 409 Conflict by refreshing data, then retrying.

Don’ts

Common pitfalls to avoid

Don’t retry 4xx errors (except 401 and 429) without fixing the request.
Don’t ignore error details - use codes/messages for debugging.
Don’t t retry indefinitely - always enforce a max retry limit (3–5 attempts).
Don’t expose raw errors to end users; provide friendly, actionable messages.
Don’t ignore 409 Conflict responses - always fetch the latest data before retrying.

U4 ERPx

API Reference

Welcome to the ERPx API Reference. This documentation provides a structured collection of RESTful endpoints, organized to match the ERPx user interface for ease of navigation and familiarity.

Handling API responses

Status code categories

Common status codes

Success responses

Client error responses

Server error responses

Detailed error scenarios

409 Conflict errors

404 Not Found errors

Invalid endpoint

Resource doesn’t exist

422 Validation errors

Error handling best practices

Do’s

Don’ts