# Errors (/docs/errors)

The error envelope, the HTTP status codes and the error codes.

Every response is JSON with a `success` field.
A successful call has `"success": true` and its result in `data`.
A failed call has `"success": false` and an `error` object:

```json
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API key. Send it as `Authorization: Bearer gm_live_...`.",
    "context": { "errorType": "authentication", "failureReason": "missing_token" }
  },
  "meta": { "timestamp": "2026-11-18T12:00:00.000Z", "version": "v1" }
}
```

| Field | Always present | What it holds |
| --- | --- | --- |
| `error.code` | Yes | A stable code. Branch on this. |
| `error.message` | Yes | A sentence for people. It can change, so do not parse it. |
| `error.context` | No | The kind of error in `errorType`, with fields for that kind. |
| `error.details` | No | Extra data. For a `429`, the limit and `resetTime`. |
| `error.validation` | No | For a `422`, one entry per invalid field. |
| `meta.requestId` | No | Our ID for the request. Send it to us when you report a problem. |

## Codes [#codes]

| HTTP status | `error.code` | Meaning | What to do |
| --- | --- | --- | --- |
| `400` | `BAD_REQUEST` | Apply only. The account has no resume, or the posting was flagged as suspicious. | Read `error.message`. Nothing was sent. |
| `401` | `UNAUTHORIZED` | The key is missing, malformed, unknown or revoked. | Check the `Authorization` header. See [Authentication](/docs/authentication). |
| `402` | none: `"error": "limit_reached"` | The account that owns the key has no API tokens left. | Buy an API token pack, then retry. The call spent nothing. |
| `403` | `FORBIDDEN` | Apply, approve and cancel only. The key was made without "Can send applications". | Create a key with it ticked. Nothing was sent. See [Key scopes](/docs/key-scopes). |
| `404` | `NOT_FOUND` | No application with that id on your account. | Use the id `POST /developer/apply` answered with. |
| `422` | `VALIDATION_ERROR` | The request body or query does not match the schema. | Read `error.validation` and fix the fields it names. |
| `422` | none: `"outcome": "not_applied"` | Apply only. GetMattered cannot apply to this posting. `reason` says why. | See [Apply to a job by API](/docs/guides/apply-to-a-job). Nothing was sent or spent. |
| `429` | `RATE_LIMIT_EXCEEDED` | The key made more than 60 requests in a minute. | Retry after `error.details.resetTime`. |
| `429` | `APPLIES_IN_FLIGHT_LIMIT` | Apply only. 5 applications started by API are already in progress. | Call again once one is sent or held for review. |
| `503` | `SERVICE_UNAVAILABLE` | Apply only. The posting is still being read. | Retry after the `Retry-After` header. |
| `5xx` | varies | The call failed on our side. | Retry with backoff. The call spent the work it used and the request fee. |

## Out of tokens [#out-of-tokens]

The account that owns the key pays for every call in API tokens, from its API balance.
The API balance is separate from the GetMattered app plans.
When it has no API tokens left, the call runs no work and gets `402` with the `limit_reached` body:

```json
{
  "success": false,
  "error": "limit_reached",
  "limit": { "action": "ai_tokens", "current": 0, "max": 560, "period": "balance", "planTier": null },
  "message": "This account is out of API tokens. Buy API tokens at https://getmattered.com/dashboard/developers#api-balance, then call again."
}
```

`limit.current` is what the account could spend. `limit.max` is what the call needed to start.
Do not retry until the account has API tokens again. `GET /developer/balance` tells you when it does.
See [Pricing](/docs/pricing).

## Key cannot apply [#key-cannot-apply]

A key made without "Can send applications" gets `403` with `error.code` `FORBIDDEN` from `POST /developer/apply`, approve and cancel.
Nothing was sent. A key's powers are fixed when it is made, so create a new key with the box ticked.
See [Key scopes](/docs/key-scopes).

## Validation errors [#validation-errors]

A field that fails validation gets `422` and one entry per field in `error.validation`:

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "validation": [
      {
        "code": "too_small",
        "field": "resumeText",
        "message": "Too small: expected string to have >=50 characters"
      }
    ]
  },
  "meta": { "timestamp": "2026-11-17T12:00:00.000Z" }
}
```

Request bodies are strict. The API also rejects a field the schema does not list.