General

Please make sure to also familiarise yourselves with the 🎓 General Concepts regarding technical topics including:

• ❓ What is Participant ID
• 👥 Roles and Permissions
• ⛔ Errors and Validations
• 📊 Data Formats

Handling MTUs

Empire is working with Market Time Units (MTUs) when handling the "time resolution" of the Auctions, Nominations, etc. The system is prepared to handle 60 minute, 30 minute and 15 minute MTUs for each Platform functionality resulting in a delivery day being split into 24, 48 or 96 chunks respectively (on a standard, non-DST day).

💡 Although Empire is prepared for it, the MTU resolution used in any functionality is not expected to change without notice - any change in them will be communicated towards Participants in due time.

The best practice to handle the (possibly dynamic) nature of the MTUs is to do the following general 2-step process:

1. Rely on the system calculating the right MTUs for you

• always use the respective "get" endpoint to fetch the list of MTUs to be submitted
• for example first fetch getTimescaleNominations for your desired delivery day, direction, etc
• be prepared that the list of MTUs can be of variable length based on the delivery day being a long or short day

2. Make use of the returned list of MTUs

• when constructing your "submit" request, map the mtu values from Step #1 to always match what is expected by Empire to be submitted
• for example send your submitTimescaleNominations request with the mapped list of MTUs
• enjoy the benefit of not needing to calculate exact UTC timestamps and handling long or short days

Handling Validations

Every endpoint in the specification have their validations and possible error cases thoroughly defined in the non 2xx error codes. The best practice for handling Platform Validations is to observe the API specification and try to prepare your integration code to avoid hitting the validations.

1) User authentication

For authenticated endpoints User authentication will be checked first and will immediately result in a 401 Unauthorized HTTP status if the check failed

Solution: To avoid hitting these validations make sure you always use a valid API Key when submitting your API requests.

⚠️ It is the Participants' responsibility to securely store API Keys and implement a rotation mechanism which changes the API Keys at least every 90 days, Empire won't enforce key rotation.

2) Permission check

The second step on validating requests is to check for the necessary Permissions which are required to perform the request. Each Role a User can have in Empire has a set of Permissions assigned to them.

Solution: To avoid hitting the Permission validations please make sure you use an API Key that belongs to a User which has the necessary Role (and thus Permission) to perform the operation.

💡 Changes in the assigned Permissions to a specific role won't be expected to change on-the-fly: any change in the permission matrix will be communicated towards the Participants.

3) Business Validations

The various business validations are encapsulated under the 400 Bad Request, 422 Unprocessable Entity and 409 Conflict HTTP statuses with specific error codes (e.g MTU_LIST_MISALIGNED) assigned to each validation.

Solution: When writing your integration code, please study the specification carefully and follow either of the following approaches:

1. write your code to ensure that validations won't be hit with the inputs you specify
   • for example in submitTimescaleNominationsin order to avoid hitting the INVALID_NOMINATION_VALUE validation, make sure you submit
     • a value for each MTU between 0 and the number of your available Transmission Rights
     • or between the flooredValue and your TRs in case the MTU is in FLOORED state
2. prepare for your request being rejected and handle validation errors
   • errors can and should be handled individually using the code field returned in the error response (e.g INVALID_NOMINATION_VALUE)

Rate Limiting

In order to prevent DDoS attacks or any third party overloading the system, Empire has two levels of Rate Limiting for API requests:

Request Type	Rate Limit
non-authenticated a.k.a public API calls	250 requests / 5 minutes / IP address
authenticated API calls using an API Key	500 requests / 5 minutes / API Key