Errors
How the API reports errors and what each code means.
The API returns errors in the standard GraphQL errors array; the HTTP status stays 200 and data may be null or partial. Each error says what kind it is in extensions.code, and a refused request says why in extensions.reasonCode.
{
"errors": [
{
"message": "Input does not meet data validation rules.",
"path": ["issueCreate"],
"extensions": {
"code": "VALIDATION",
"reasonCode": "REQUIRED",
"field": "issueCreate.title",
"reason": "title is required"
}
}
],
"data": null
}Errors on any request
These can be returned by any operation across the whole API.
UNAUTHENTICATEDYour API key is missing, invalid or expired.RATE_LIMITYou have sent too many requests; wait before retrying.INTERNALAn unexpected server error occurred; retry later.Specific errors
Depending on the operation and the input you send, a request may also return:
NOT_FOUNDThe resource does not exist or your organization cannot access it.VALIDATIONThe request was refused because of what it asked for. extensions.reasonCode says why: see Refusals below.INPUTAn ID or a token that cannot be read: a bug in the client or a broken link, never something a person typed. Treat it like NOT_FOUND.CONSTRAINTTwo requests raced for the same write and this one lost. Retrying usually works.Refusals
A refused request is always VALIDATION, with these extensions. Switch on reasonCode, never on message, which is the same sentence for every refusal.
reasonCodeWhy the request was refused, as a stable word. Use it as your translation key.fieldWhere in the request the problem is: the operation name, then the path into what you sent, without the input wrapper and with list positions from zero (domainUpdate.nameServers[1]). Absent when the refusal is about the whole request.paramsValues the explanation needs, such as kind or a hostname. Absent when there are none.reasonThe same explanation in English, for developers. Not meant to be shown to users.Reasons any operation can give
Besides the reasons listed under each operation, any of them may answer with these. For the last four, params.kind says what kind of thing the refusal is about (PROJECT, DNS_ZONE, DNS_RECORD…).
MALFORMEDA value does not have the expected form. reason says what is wrong.REQUIREDA value is missing, or null was sent for a field that cannot be cleared.TOO_LARGEA text or a file is larger than allowed. params.maxBytes is the limit.NOT_FOUNDSomething the request refers to does not exist, or belongs to another organization.TAKENThe name is already used by something else.IN_USEIt cannot be removed while something still uses it.DELETEDIt is deleted, and nothing can be changed on it until it is restored.