> ## Documentation Index
> Fetch the complete documentation index at: https://gecko.security/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error types, HTTP status codes, and what each Gecko API error code means.

Every failed request returns an `error` object. Branch on `code`, which stays
stable. `message` is written for people and can change.

```json theme={null}
{
  "error": {
    "type": "invalid_request",
    "code": "parameter_missing",
    "message": "Missing required parameter: repository.",
    "param": "repository",
    "doc_url": "https://gecko.security/docs/api-reference/errors#parameter_missing",
    "request_id": "…"
  }
}
```

| Field | Meaning |
| - | - |
| `type` | The error family. Each type maps to one HTTP status. |
| `code` | The specific failure, listed on this page. |
| `message` | A readable explanation. |
| `param` | The offending parameter, when there is one. |
| `doc_url` | A link to this page, at the entry for `code`. |
| `request_id` | The ID to include when you contact support. It matches the `X-Request-Id` response header. |

## Authentication errors

Type `authentication_error`, status `401`.

| Code | Meaning | What to do |
| - | - | - |
| `api_key_invalid` | The API key is missing or invalid. | Send a valid key in the `X-API-Key` header or as `Authorization: Bearer <key>`. |

## Authorization errors

Type `authorization_error`, status `403`.

| Code | Meaning | What to do |
| - | - | - |
| `permission_denied` | The key isn't allowed to make this request. The message gives the reason. | Use a key with the permission, or fix what the message describes. |
| `tier_required` | The team's plan doesn't include API access. | Move the team to a Pro or Enterprise plan. |
| `scan_limit_reached` | The team reached its plan's scan limit. | Wait for the limit to reset, or upgrade the plan. |
| `github_not_configured` | The team has no GitHub integration. | Connect GitHub in the dashboard. |
| `gitlab_not_configured` | The team has no GitLab integration. | Connect GitLab in the dashboard. |
| `repository_access_denied` | The team's integration can't read the repository. | Check that the integration still has access to it. |
| `release_publish_restricted` | Your team can't publish scanner image releases. | Read releases with the `GET` endpoints instead. |

## Invalid requests

Type `invalid_request`, status `400`.

| Code | Meaning | What to do |
| - | - | - |
| `parameter_invalid` | A parameter failed validation. `param` names it when Gecko can. | Correct the value and retry. |
| `parameter_missing` | A required parameter is missing. | Add the parameter named in `param`. |
| `idempotency_key_invalid` | The `Idempotency-Key` header isn't 1-255 visible ASCII characters. | Send a valid key. |
| `repository_not_connected` | The repository isn't connected to this team. | Connect it in the dashboard before you scan it through the API. |
| `commit_not_found` | The commit doesn't exist in the repository. | Check the value of `commit` or `base_commit`. |
| `mixed_repository_providers` | The repositories in `repository_ids` span more than one provider. | Send one request per provider. |
| `export_too_large` | The filters match more than one SARIF export can hold. | Narrow them with `repository`, `scan_id`, `status`, or `severity`. |
| `ticketing_provider_not_configured` | The team hasn't set up this ticketing integration. | Connect the provider, or pick one the team already uses. |

## Not found

Type `not_found`, status `404`.

| Code | Meaning | What to do |
| - | - | - |
| `resource_not_found` | No resource with that ID exists for this team. | Check the ID, and that the key belongs to the right team. |

## Conflicts

Type `conflict`, status `409`.

| Code | Meaning | What to do |
| - | - | - |
| `conflict` | The request conflicts with the resource's current state. The message says how. | Fetch the resource, then retry. |
| `idempotency_key_reused` | This key was already used with a different request. | Use a new key for the new request. |
| `idempotency_in_flight` | A request with this key is still running. | Wait, then retry with the same key. |
| `idempotency_outcome_unknown` | The earlier request with this key never recorded an outcome. | Check the resource's state, then retry with a new key. |
| `repository_name_ambiguous` | The name matches repositories on more than one provider. | Add the `provider` query parameter. |
| `repository_archived` | The repository is archived on its provider, so PR tracking and push scans can't be turned on. | Unarchive it on the provider. Gecko picks up the change on its next repository sync. |
| `vulnerabilities_already_ticketed` | One or more of the findings already has a ticket with this provider. | Remove those findings from the request. |
| `ticket_fan_out_partial_failure` | Gecko created the ticket but couldn't link every finding to it. | Don't retry the request. Check which findings the ticket covers first. |
| `vulnerability_link_conflict` | Gecko is still generating a fix for the finding, that pull request is already linked, or there is no linked pull request to unlink. | Wait for the fix to finish, or link a different pull request. |

## Rate limits

Type `rate_limit_error`, status `429`.

| Code | Meaning | What to do |
| - | - | - |
| `rate_limit_exceeded` | The key reached its [hourly limit](https://gecko.security/docs/api-reference/introduction.md#rate-limits). | Wait for the number of seconds in the `Retry-After` header. |
| `limit_exceeded` | The request hit a usage limit. The message says which. | Reduce usage, or upgrade the plan. |

## Server errors

Type `api_error`, status `500`.

| Code | Meaning | What to do |
| - | - | - |
| `internal_error` | Something failed on Gecko's side. | Retry, and include `request_id` if you contact support. |

## MCP endpoint

The [MCP server](https://gecko.security/docs/ai-tools/overview.md) can also reject a request before it
reaches a tool. These errors have type `invalid_request` and no `doc_url`.

| Code | Status | Meaning | What to do |
| - | - | - | - |
| `origin_forbidden` | `403` | The request came from a disallowed browser origin. | Call the endpoint from a server or an MCP client. |
| `method_not_allowed` | `405` | The server is stateless, so `GET` and `DELETE` aren't supported. | Send JSON-RPC requests with `POST`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.