# Response Status Codes

When Echo receives a request to the EchoSync Shipper API, different HTTP status codes can be returned depending on the request and its processing.

| Status Code  | Description |
|  --- | --- |
| `200 OK` | The request was successfully processed. |
| `400 Bad Request` | The request cannot be processed due to validation errors. Invalid field formats, missing required fields, enum value mismatches, stop sequencing errors, or weight limit violations. Check the `Errors` array in the response for specific validation failures. |
| `401 Unauthorized` | Authentication credentials are missing or invalid. The access token is expired, invalid, or not provided in the Authorization header. Request a new token using your client credentials. |
| `403 Forbidden` | Valid credentials provided but account lacks API access permissions. Contact your Echo Account Team to verify permissions. |
| `429 Too Many Requests` | The request rate limit has been exceeded. Reduce request frequency and retry with exponential backoff. |
| `500 Internal Server Error` | An internal error occurred in Echo's systems. Retry your request. If the issue persists, contact support with error codes and timestamps. |


## Common Resolution Steps

### 400 Bad Request

#### Invalid enum values

- Verify uppercase values: `LB`/`KG` (UnitOfWeight), `US`/`CA` (CountryCode), `PICK`/`DROP` (StopType)
- Location types: `BUSINESS`, `RESIDENTIAL`, `CONSTRUCTIONSITE`, `TRADESHOW`


#### Date/time format errors

- Dates: `MM/dd/yyyy` format (e.g., `12/01/2025`)
- Times: `hh:mm` format (e.g., `08:00`, `14:30`)
- Postal codes: 5 digits for US; `A1A 1A1` format for Canada


#### Stop sequencing errors (TL/PL)

- Number stops starting at 1, incrementing by 1 (no gaps)
- First stop must be `PICK`, last stop must be `DROP`
- Each item's `StopPickNumber` and `StopDropNumber` must reference a valid `StopNumber`


#### Weight limit exceeded

- LTL: total weight must be under 20,000 lb (9,071 kg)
- TL/PL: total weight must be under 10,000 lb (4,536 kg)


#### Missing required fields

- LTL requires `NmfcClass` on each item
- TL/PL requires `EquipmentTypes`
- All shipments require `BolNumber`, `UnitOfWeight`, origin, and destination details


#### Notification email errors

- Use semicolons (no spaces) to separate multiple addresses
- Maximum 5 email addresses per `AckNotification` or `AsnNotification` field


### 401 Unauthorized

- Request a new access token and retry
- Verify header format: `Authorization: Bearer {token}`
- Check that client credentials are correct


### 403 Forbidden

- Confirm the account has Shipper API access enabled
- Contact your Echo Account Team to verify permissions


### 429 Too Many Requests

- Reduce request frequency
- Implement exponential backoff before retrying


## Error Response Format

All error responses use the `ResponseStatus` structure:

- **`ErrorCode`** - Error code identifier
- **`Message`** - High-level error description
- **`StackTrace`** - Internal trace (Echo support reference)
- **`Errors`** - Array of nested error objects with additional detail
- **`Meta`** - Additional metadata when applicable


The `Errors` array provides specific, actionable information to resolve validation issues.