Skip to main content

Error Codes

This page documents the error response formats and common error codes for both the ECGrid REST API (v2.6) and the ECGridOS SOAP API (v4.1).

REST API Errors​

Error Response Format​

All REST API errors return a consistent JSON envelope with success: false.

{
  "success": false,
  "errorCode": "InvalidAPIKey",
  "message": "The provided API key is not valid or has been revoked.",
  "data": null
}
FieldTypeDescription
successbooleanAlways false for error responses
errorCodestringMachine-readable error code (see table below)
messagestringHuman-readable description of the error
datanullAlways null on error

Common REST Error Codes​

Error CodeHTTP StatusDescription
InvalidAPIKey401The API key in the X-API-Key header is missing, invalid, or has been revoked.
InvalidSession401The Bearer token in the Authorization header is expired, malformed, or invalid.
AccessDenied403The authenticated user or API key does not have sufficient AuthLevel for the requested operation.
ObjectNotFound404The requested resource (mailbox, parcel, interchange, etc.) does not exist or is not accessible to the caller.
InvalidParameter400One or more request parameters are missing, the wrong type, or fail a validation constraint. Check the message field for details on which parameter failed.
RateLimitExceeded429The caller has exceeded the allowed request rate. Wait before retrying. Check the Retry-After response header for the recommended delay.
InternalError500An unexpected server-side error occurred. If this persists, contact ECGrid support.

Authentication Header Reference​

ScenarioHeader
API key authenticationX-API-Key: <your-api-key>
JWT Bearer authenticationAuthorization: Bearer <token>

See Authentication & API Keys for how to obtain and use credentials.

SOAP API Errors​

Error Response Format​

The ECGridOS SOAP API returns errors as standard SOAP Faults. The fault detail contains an ECGridOSSOAPErrorCode element that identifies the specific error.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Client</faultcode>
      <faultstring>Invalid Session ID</faultstring>
      <detail>
        <ECGridOSSOAPErrorCode>Authentication</ECGridOSSOAPErrorCode>
      </detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>
ElementDescription
faultcodesoap:Client for caller errors; soap:Server for server-side errors
faultstringHuman-readable error description
ECGridOSSOAPErrorCodeMachine-readable ECGridOS error category

Common SOAP ECGridOSSOAPErrorCode Values​

CodeDescription
AuthenticationThe SessionID parameter is missing, expired, or invalid. Obtain a new session via Login().
AuthorizationThe session does not have sufficient permission for the requested operation.
ObjectNotFoundThe requested object (network, mailbox, ECGrid ID, etc.) does not exist.
InvalidParameterOne or more method parameters are invalid or out of range.
SystemErrorAn unexpected server-side error occurred. Contact ECGrid support if the issue persists.

:::caution Established API The SOAP API is in maintenance mode. For new integrations, use the REST API instead. :::

Handling Errors in C#​

REST — Checking for Errors​

// .NET 10 — check the success flag before using data
var response = await httpClient.GetAsync("https://rest.ecgrid.io/v2/mailbox/12345");
var json = await response.Content.ReadFromJsonAsync<ApiResponse<MailboxInfo>>();

if (json is null || !json.Success)
{
    Console.Error.WriteLine($"Error [{json?.ErrorCode}]: {json?.Message}");
    return;
}

// Safe to use json.Data here

SOAP — Catching SOAP Faults​

// .NET 10 — dotnet-svcutil generated proxy
try
{
    var result = await client.MailboxInfoAsync(sessionID, mailboxID);
}
catch (FaultException ex)
{
    // ex.Message contains the faultstring
    Console.Error.WriteLine($"SOAP Fault: {ex.Message}");
}

See Also​