Skip to main content

Conventions

Standards and conventions shared across all the endpoints of the API.

Headers

  • X-Correlation-ID: In order to easily identify a request on all of 1GLOBAL's subsystems, we require that requesters create a unique identifier that will be sent on every request header when (X-Correlation-ID) using the api. This way we can easily identify a request or a sequence of events between both 1GLOBAL and the requester.

Metadata

The Metadata object is present on all responses and it is based on the Hypertext Application Language (HAL). HAL is an Internet Draft standard convention for defining hypermedia such as links to external resources within JSON or XML code. Connect Metadata is based on this standard to describe links to other resources in the API. These links enable navigation to other resources directly from response payloads, making the integration with the API easier.

Dates

Dates in requests and responses are treated and stored in the UTC timezone.

Errors

All errors thrown by 1GLOBAL Connect API use the same data model in order to facilitate error handling:

{
"type": "ERROR_TYPE",
"messages": [
"error_message_1",
"error_message_2",
"..."
]
}

Shared error types

Common error types, shared by all endpoints

  • INVALID_HTTP_MESSAGE (400) - Parsing of the HTTP request has failed. Usually there's a syntax error in either the JSON body or one of the JSON fields such as dates.
  • INVALID_REQUEST_PARAMS (400) - Request was parsed successfully but it contains semantic errors like missing required fields or invalid content like non existing currencies or countries.
  • UNAUTHORISED (401) - OAuth2 token is missing invalid.
  • ACCESS_DENIED (403) - Client is trying to access a resource that it doesn't own like eSIM profiles or customer accounts from other clients.
  • UNACCEPTABLE (406) - Client has exceeded the daily / monthly eSIM resource limit.
  • TOO MANY REQUESTS (429) - Client has exceeded the rate limit (number of requests that can be made per minute).
  • INTERNAL_ERROR (500) - Something went wrong with the request and the API can't recover. These should not happen on normal circumstances, and partners are advised to report back to 1GLOBAL, with the correlation id that generated such error.