Skip to content
On this page

Account API

Error responses

How the API reports problems, and what each status code means.

Error format

Errors use standard HTTP status codes and a JSON body with a human-readable message. Validation errors add an errors object. Error bodies are JSON even when the Accept header is missing.

Response

401
{
  "message": "Unauthenticated."
}
Branch on the HTTP status code, not on the message text. Messages are written for people and may change.

Status codes

StatusMeaning
200 OKThe request worked. The result is in data.
401 UnauthorizedThe token is missing, invalid or revoked.
403 ForbiddenThe token lacks a required ability, or you cannot access this resource.
404 Not FoundThe resource or the path does not exist.
405 Method Not AllowedThe path exists but does not accept this HTTP method.
422 Unprocessable ContentThe request data failed validation.
429 Too Many RequestsYou went over the rate limit.
500 Server ErrorSomething went wrong on our side. Try again later.

401 Unauthenticated

The Authorization header is missing, or the token in it is invalid or has been revoked. Check that you send Bearer followed by the full token.

Response

401
{
  "message": "Unauthenticated."
}

403 Forbidden

The token is valid but not allowed to do this. When the token lacks the ability an endpoint needs, the message is:

Response

403
{
  "message": "Invalid ability provided."
}

When you ask for a team you are not a member of, the message is:

Response

403
{
  "message": "This action is unauthorized."
}

404 Not found

No team has the slug you asked for, or the path does not exist. Remember that a team's slug changes when the team is renamed.

Response

404
{
  "message": "No query results for model [App\\Models\\Team] unknown-team"
}

Response

404
{
  "message": "The route api/v1/unknown could not be found."
}

422 Validation failed

Returned when request data fails validation. No v1 endpoint accepts input yet, so you will not see this today. Endpoints that accept input will report problems in this shape, with one entry per invalid field:

Response

422
{
  "message": "The <field> field is required.",
  "errors": {
    "<field>": [
      "The <field> field is required."
    ]
  }
}

429 Too many requests

You made more than 60 requests in a minute. Retry-After tells you how many seconds to wait before the next request.

HTTP

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1794483139

{"message": "Too Many Attempts."}

Spread requests out, cache responses you reuse, and retry after the wait instead of in a tight loop.