Error model

The exception hierarchy, what an exception carries, and forward compatibility on the read side.

Exception hierarchy#

All SDK exceptions are unchecked and extend BaseException.

HTTP status	Exception
401	`EquinixAuthenticationException`
403	`EquinixAuthorizationException`
404	`EquinixNotFoundException`
409	`EquinixConflictException`
429	`EquinixRateLimitException`
5xx	`EquinixServerException`
Any other error status	`EquinixServiceException`
No HTTP response: transport, serialization or configuration failure	`EquinixClientException`
Circuit breaker open	`CircuitOpenException`

The six status-specific classes extend EquinixServiceException, so one catch clause can handle every API error.

Java

import com.eqixiac.equinix.core.exception.EquinixConflictException;
import com.eqixiac.equinix.core.exception.EquinixNotFoundException;
import com.eqixiac.equinix.core.exception.EquinixServiceException;
import com.eqixiac.equinix.core.exception.ExceptionDetail;
import com.eqixiac.equinix.fabric.model.Connection;

try {
    Connection connection = fabric.connections().getByUuid(connectionUuid);
    connection.delete();
} catch (EquinixNotFoundException e) {
    // already gone: treat as success for an idempotent teardown
} catch (EquinixConflictException e) {
    // the resource is in a state that does not allow the operation
} catch (EquinixServiceException e) {
    System.err.println(e.getStatusCode() + " " + e.getPath() + " correlation " + e.getCorrelationId());
    for (ExceptionDetail detail : e.getExceptionDetails()) {
        System.err.println(detail.getErrorCode() + " " + detail.getErrorMessage()
            + (detail.getProperty() != null ? " at " + detail.getProperty() : ""));
    }
}

Content of a service exception#

Accessor	Content
`getStatusCode()`	HTTP status
`getPath()`	Request path
`getCorrelationId()`	The `X-Correlation-Id` sent with the request
`getHttpHeaders()`	Response headers
`getExceptionDetails()`	The parsed error list: `errorCode`, `errorMessage`, `details`, `property`, `correlationId`, `help`, `additionalInfo`
`getResponseBodySnippet()`	The start of the raw body, for a body that is not the documented error shape
`getMessage()`	A one-line summary built from the fields above; null fields are omitted

An Equinix error code identifies the rule that rejected the request. The following two codes were returned during live validation on 2026-11-11.

Code	Status	Meaning
`EQ-3142501`	400	"Invalid seller metroCode location": a service-provider Z-side without `location.metroCode`
`EQ-3045002`	400	A `limit` parameter on `GET /{asset}/{id}/metrics`, which accepts none

STS errors use the OAuth shape {"error", "error_description"}. The SDK maps them to the same exception classes.

Forward compatibility#

The SDK reads responses so that a field or value added by a newer API version does not fail the call.

The shared JSON mapper disables FAIL_ON_UNKNOWN_PROPERTIES, so a property that the SDK does not model is ignored. Release 3.0.0 set this per model, and a response for a model without the annotation failed as a whole against the live service.
Unknown enum values deserialize to an UNKNOWN constant where the enum has one. The raw value stays available on models that keep it, for example Metro.metroId() for a metro the MetroCode enum does not list.
Timestamps with 0 to 9 fractional digits and with Z, +HH, +HHMM or +HH:MM offsets are accepted and normalized to UTC.

Where the live service and the specification disagree on the shape of a field, the SDK reads both shapes. For example, Fabric GET /health returns apiServices as an array where the specification types an object, Metric.summary is an object where the specification types a string, and Network Edge DeviceCore.tier is an array for some device types. The upgrade notes list each case.

Fail-fast argument checks#

Some services answer a missing mandatory argument with a 400 or 500 that does not name the argument. For the following cases the SDK rejects the call before sending it and names the argument in the exception message.

IBX SmartView asset calls require accountNo, ibx and classification.
A URI template with an unresolved placeholder fails with the name of the token and the endpoint.
zSideCloudProvider(adapter, linkProtocol) throws IllegalArgumentException when the adapter carries no metro.