Errors and limits

Status codes

200 OK

A read answered.

201 Created

A write was done.

400 Bad Request

The request can’t be done as written, such as a note with nothing in it or a status the project doesn’t have.

401 Unauthorized

No key or token, or one the API doesn’t take. See Authentication.

403 Forbidden

You can read the project but not change its work.

404 Not Found

A project you can’t open, or a job, criterion or pull request that isn’t there.

409 Conflict

The job already has what you asked for, or can’t take it, such as a pull request that is already linked.

429 Too Many Requests

More than 120 calls in a minute. See Rate limit.

503 Service Unavailable

GitHub didn’t answer, so no pull request was linked. Try again shortly.

Refusals

A refusal’s body says why, in a sentence:

{
  "message": "You can read this project but not write to it, so this was not done."
}

• Have your program act on the status code. The message is written for people, so show it to whoever runs the program.
• It is the same sentence Claude and other MCP clients are given for the same refusal.
• A 401 and a 429 have no body.
• A body that isn’t JSON, or is missing a field the call needs, is refused with 400 and a standard problem document (RFC 9457) in place of a sentence. Its errors name what is wrong.

Projects you can’t open

Every project you can’t open gets the same 404: one in another workspace, one you aren’t a member of, and a key that matches no project.

{
  "message": "No project with that key is open to you."
}

So nobody can find out which projects exist by trying keys. If you expected to reach the project, check its key and that you are a member of it. An API key reaches only the workspace it was made in, so a project in another of your workspaces gets this answer too.

Rate limit

Each person can make 120 calls a minute through the API, counted across all their keys and tokens. Calls Claude makes over MCP are counted separately.

Over the limit, calls are answered 429 for the rest of that minute. The answer has no Retry-After header, so wait a minute before trying again. The clients on Examples wait and try again for you.

Trying again

• Reads are safe to repeat.
• A write refused with 503 did nothing, so it is safe to repeat.
• If a write gets no answer at all, such as when the connection drops, check before you repeat it. Read the job’s notes before posting a note again, for example. A second proposal on a job is refused while the first one waits, and a pull request that is already linked is refused with 409.

What the audit log records

Every call made in a workspace is recorded in its audit log, including calls that were refused.

• Each is recorded as api. followed by the operation’s name, such as api.get_job or api.post_note.
• The record names the person, your program’s User-Agent, the key’s name and ID when a key was used, the project and job keys, and whether the call was refused.
• Nothing from the body is copied into the record: no titles, notes or evidence. A key’s value is never recorded.
• A linked pull request is also recorded as api.pull_request_linked.
• Making and revoking a key are recorded as api_key.created and api_key.revoked.

The User-Agent is whatever your program says it is, so treat it as a label rather than proof of identity. Owners and admins read and export the audit log. See Activity and audit log.