Errors

The Partner API uses standard HTTP response codes to indicate the success or failure of a request. Codes in the 2xx range indicate success, codes in the 4xx range indicate a problem with the request, and codes in the 5xx range indicate an error on our side.

In addition to the status code, error responses have a JSON body that tells you the error type and, where possible, which field caused it.

Error ResponseCopy Anchor Link

{
  "type": "VALIDATION_ERROR_INVALID_VALUE",
  "details": {
    "ref": "createServiceLineDetail.starlinkDeviceRefIds",
    "message": "starlinkDeviceRefId#XXXX00000001 is associated with service line"
  }
}

HTTP Status CodesCopy Anchor Link

Error TypesCopy Anchor Link

VALIDATION_ERROR_REQUIREDCopy Anchor Link

• Status: 400
• Message: A required field or parameter is missing or null.
• Suggested action: Provide the field named in details.ref. Check the endpoint's documentation for which fields are required, including fields that are only required for certain request types.

VALIDATION_ERROR_INVALID_FORMATCopy Anchor Link

• Status: 400
• Message: A value cannot be parsed as the expected type or format — for example, text where a number is expected, a date not in yyyy-MM-dd format, an unrecognized enum value, or a value that is too long.
• Suggested action: Correct the value at details.ref to match the type and format in the endpoint's documentation and the data type formats.

VALIDATION_ERROR_INVALID_VALUECopy Anchor Link

• Status: 400
• Message: A value is well-formed but not acceptable — for example, it is out of range, refers to a resource that does not exist or does not belong to your account, or breaks a business rule.
• Suggested action: Check details.message for the reason, then correct the value at details.ref.

VALIDATION_ERROR_CONTAIN_DUPLICATECopy Anchor Link

• Status: 400
• Message: An array contains the same value more than once.
• Suggested action: Remove the duplicate values from the array at details.ref.

VALIDATION_ERROR_DUPLICATEDCopy Anchor Link

• Status: 400
• Message: The value conflicts with an existing resource, for example a tag with the same label already exists.
• Suggested action: Use a different value, or update the existing resource instead.

VALIDATION_ERROR_EXPECT_NULLCopy Anchor Link

• Status: 400
• Message: A field was provided where it is not applicable to the rest of the request.
• Suggested action: Omit the field at details.ref, or set it to null.

CANNOT_CREATECopy Anchor Link

• Status: 400
• Message: The request is valid, but the resource cannot be created in the current state.
• Suggested action: Check details.message for the reason and resolve it before retrying.

CANNOT_UPDATECopy Anchor Link

• Status: 400
• Message: The request is valid, but the resource cannot be updated in its current state — for example, the action is not available for the resource's current status.
• Suggested action: Retrieve the resource to check its current state, and check details.message for the reason.

CANNOT_DELETECopy Anchor Link

• Status: 400
• Message: The resource cannot be deleted because it is still in use — for example, a Starlink device still assigned to a service line, or a tag still applied to resources.
• Suggested action: Remove what is using the resource first, then retry.

NOT_SUPPORTEDCopy Anchor Link

• Status: 400
• Message: The action is not supported for this resource, for example a SIM operation that only applies to a different SIM type.
• Suggested action: Check details.message and the endpoint's documentation for which resources the action supports.

ACCESS_TOKEN_REQUIREDCopy Anchor Link

• Status: 401
• Message: The request has no API key.
• Suggested action: Send the API key in the Authorization: Bearer <api-key-token> header. See Authentication.

ACCESS_TOKEN_INVALIDCopy Anchor Link

• Status: 401
• Message: The API key does not exist or has been revoked.
• Suggested action: Check that the full API key is sent, or create a new one from the API Keys page.

FORBIDDENCopy Anchor Link

• Status: 403
• Message: The API key is not allowed to perform this request — usually because it does not have the capability the endpoint requires.
• Suggested action: Check the endpoint's Required Capabilities section and assign the missing capability to the API key. See Capabilities.

NOT_FOUNDCopy Anchor Link

• Status: 404
• Message: The resource in the request path does not exist or does not belong to your account.
• Suggested action: Check the ID in the request path. You can use the corresponding search endpoint to find valid IDs.

TOO_MANY_REQUESTSCopy Anchor Link

• Status: 429
• Message: The API key has sent too many requests in a short period of time and has reached its rate limit. By default, the rate limit is 120 requests per 60-second window.
• Suggested action: Wait for the rate limit window to reset before retrying, and spread requests out over time.

HTTP_STATUS_ERRORCopy Anchor Link

• Status: Varies — 400, 415 or 5xx
• Message: A general error not covered by the types above — for example, the request body is not valid JSON (400), the Content-Type: application/json header is missing (415), or an unexpected error occurred on our side (5xx). details.code and details.description hold the HTTP status code and its standard description.
• Suggested action: For 400 and 415, check that the request body is valid JSON and is sent with the Content-Type: application/json header. For 5xx, retry later.

{
  "type": "HTTP_STATUS_ERROR",
  "details": {
    "code": 500,
    "description": "Internal Server Error"
  }
}