# Response Status Codes

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

## 200 OK

Token issued successfully.

| Field  | Type | Description |
|  --- | --- | --- |
| `access_token` | string | JWT Bearer token. Pass this in the `Authorization: Bearer <token>` header of every downstream API request. |
| `expires_in` | integer | Token lifetime in seconds (e.g. `86400` = 24 hours). Cache and reuse the token for this entire duration. |
| `token_type` | string | Always `Bearer`. |
| `scope` | string | Space-delimited list of scopes approved for this token. |


## 400 Bad Request

The request was malformed or missing required fields.

| Field  | Type | Description |
|  --- | --- | --- |
| `error` | string | Short error code identifying the failure type (e.g. `invalid_request`, `invalid_grant`). |
| `error_desc` | string | Human-readable explanation of the specific failure. Use this to diagnose the root cause. |


Three distinct scenarios return a `400`:

#### Missing required parameter

Triggered when one or more required fields (`client_id`, `client_secret`,
`grant_type`, `scope`) are absent from the request body.

```json
{
  "error": "invalid_request",
  "error_desc": "missing required parameter(s). (redirect_uri)"
}
```

**Fix:** Confirm all four required fields are present and correctly named in
your `application/x-www-form-urlencoded` body. Also verify:

- `Content-Type` is `application/x-www-form-urlencoded` (not `application/json`)
- `grant_type` is set to exactly `client_credentials`
- Scopes are space-delimited (e.g. `quotes:create loads:read`)


#### Invalid client

Triggered when the `client_id` cannot be resolved.

```json
{
  "error": "invalid_request",
  "error_desc": "Resource not found"
}
```

**Fix:** Verify your `client_id` is correct and matches what was issued by
your Echo Account Team. Check for typos or trailing spaces.

#### Invalid grant

Triggered when the grant has already been used or has expired.

```json
{
  "error": "invalid_grant",
  "error_desc": "grant request is invalid"
}
```

**Fix:** Request a fresh token. Do not reuse a grant after it has been
consumed or expired.

## 401 Unauthorized

Authentication failed. The credentials are incorrect, inactive, or not
authorized for the requested scope. Also returned by downstream EchoSync
APIs when a cached token has expired, catch this code to trigger token
renewal.

| Field  | Type | Description |
|  --- | --- | --- |
| `error` | string | Short error code identifying the failure type (e.g. `invalid_request`). |
| `error_desc` | string | Human-readable explanation of the specific failure. Use this to diagnose the root cause. |


Two distinct scenarios return a `401`:

#### Authentication failed

Triggered when the `client_id` and `client_secret` combination fails
validation.

```json
{
  "error": "invalid_request",
  "error_desc": "Authentication Failed"
}
```

**Fix:** Double-check that your `client_secret` has no missing characters,
trailing spaces, or typos, and that `client_id` was copied exactly as issued.
Contact your Echo Account Team if valid credentials are consistently rejected,
or if your integration profile may have been suspended or rotated.

#### Access unauthorized

Triggered when the credentials are valid but the application is not permitted
to access the requested scope.

```json
{
  "error": "invalid_request",
  "error_desc": "Access is unauthorized"
}
```

**Fix:** Confirm the scope(s) you are requesting have been granted to your
application. Contact your Echo Account Team to review your integration's
permission profile.

#### Downstream token expiry

If a downstream EchoSync API returns a `401`, your cached token has expired, then
call `POST /token` to get a new one and retry.