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:
{
"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
| 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. |
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. |
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. 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
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:
{
"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.
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.
Validation errors
A field that fails validation gets 422 and one entry per field in error.validation:
{
"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.