Skip to content

Error handling

The AtomGit API returns different status codes depending on the request context. Error response bodies are JSON and the message field explains the cause; the 401 body looks like this:

{
  "message": "401 Unauthorized"
}

When troubleshooting, start with the status code class: 4xx is a problem with the request itself (parameters, authentication, permission, missing resource) and only passes once you change the request; 5xx is a server-side problem and can be retried.

Request types and expected results

Request type Description
GET Access one or more resources and return the result as JSON
POST Return 201 Created and the newly created resource as JSON when the resource is created successfully
GET / PUT Return 200 OK and the (updated) result as JSON when the resource is accessed or modified successfully
DELETE Return 204 No Content when the resource is deleted successfully; return 202 Accepted when deletion is scheduled

Status code reference

Value Description
200 OK The GET, PUT, or DELETE request succeeded and the resource itself is returned as JSON
201 Created The POST request succeeded and the resource is returned as JSON
202 Accepted The GET, PUT, or DELETE request succeeded and the resource is scheduled for processing
204 No Content The server met the request successfully and there is no additional content to send in the response payload
301 Moved Permanently The resource has been located at the URL given by the Location header
304 Not Modified The resource has not been modified since the last request
400 Bad Request A required attribute of the API request is missing, for example when the issue title is not given
401 Unauthorized The user is not authenticated and a valid user token is required
403 Forbidden The request is not allowed, for example when the user is not permitted to delete the project
404 Not Found The resource cannot be accessed, for example when the resource ID cannot be found or the user has no permission to access the resource
405 Method Not Allowed The request method is not supported
409 Conflict A conflicting resource already exists, for example when creating a project with a name that is already taken
412 Precondition Failed The request was rejected, for example when a request with an If-Unmodified-Since header deletes a resource that was modified in the meantime
418 I'm a teapot The request was rejected because it is suspected to be unsafe
422 Unprocessable The entity cannot be processed
429 Too Many Requests The user exceeded the application rate limit, which defaults to 400 per minute and 4000 per hour
500 Server Error Something went wrong on the server while processing the request
503 Service Unavailable The server is temporarily overloaded and cannot handle the request
504 Time Out The response timed out

Common handling steps

  • 401: Confirm the token is actually sent with the request (see Authentication for the three ways) and that it has not expired.
  • 403: The token is valid but lacks permission; check the token scopes and the visibility of the resource.
  • 404: Check the path parameters (such as {owner}, {repo}, and IDs) against the actual resource. Private resources may also return 404 when you have no permission.
  • 422 / 400: Check required fields and accepted values against the parameter table on the endpoint page.
  • 429: Back off according to the returned rate limit information before retrying, and do not keep sending concurrent requests after reaching the limit.
  • 5xx / 504: Temporary server-side or network problems; retry with exponential backoff. For state-changing requests such as POST, confirm whether the previous attempt took effect before retrying to avoid creating duplicates.
  • OpenAPI quick start: API hosts, version prefix, and pagination
  • Authentication: token types and the three ways to send them
  • API reference: browse all endpoints by category

Markdown source: View on AtomGit·Content from the open-source project gitcode-dev/atomgit-api-doc