HTTP Status Codes

The Bifrost API uses standard HTTP status codes to indicate the success or failure of a request. Every response returns JSON — even errors.

Overview

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

429 Too Many Requests

500 Internal Server Error

503 Service Unavailable

Response Examples

200 OK

The request succeeded. The response body contains the requested data. Note: GraphQL may return 200 even if there are partial errors — always check the errors array in the response.

{
  "data": {
    "playerStats": {
      "kills": 1523,
      "deaths": 987,
      "winRate": 0.54
    }
  }
}

400 Bad Request

The request body is malformed or the GraphQL query has syntax errors. Check your query string, variables, and JSON formatting.

{
  "errors": [
    {
      "message": "Syntax Error: Expected Name, found \"}\".",
      "locations": [
        {
          "line": 3,
          "column": 1
        }
      ]
    }
  ]
}

401 Unauthorized

No valid authentication token was provided. Make sure you include a valid Bearer token in the Authorization header.

{
  "errors": [
    {
      "message": "Not authenticated. Please provide a valid Bearer token.",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}

403 Forbidden

Your token is valid but does not have permission to access this resource. Check your API scopes and subscription tier.

{
  "errors": [
    {
      "message": "You do not have permission to access this resource.",
      "extensions": {
        "code": "FORBIDDEN"
      }
    }
  ]
}

429 Too Many Requests

You have exceeded the rate limit. Back off and retry after the time indicated in the Retry-After header. See the Rate Limiting page for details.

{
  "errors": [
    {
      "message": "Rate limit exceeded. Please retry after 30 seconds.",
      "extensions": {
        "code": "RATE_LIMITED",
        "retryAfter": 30
      }
    }
  ]
}

500 Internal Server Error

Something went wrong on our end. These are automatically logged and investigated. If the problem persists, contact support.

{
  "errors": [
    {
      "message": "Internal server error.",
      "extensions": {
        "code": "INTERNAL_SERVER_ERROR"
      }
    }
  ]
}

503 Service Unavailable

The API is temporarily unavailable, usually during a deployment or maintenance window. Retry with exponential backoff.

{
  "errors": [
    {
      "message": "Service temporarily unavailable. Please try again later.",
      "extensions": {
        "code": "SERVICE_UNAVAILABLE"
      }
    }
  ]
}

GraphQL Error Format

GraphQL has its own error format that lives inside the JSON response body. Even when the HTTP status is 200 OK, the response may contain an errors array alongside partial data.

Always check for the presence of the errors key in the response, even on successful HTTP status codes. Each error object includes:

message — A human-readable description of the error
locations — Where in the query the error occurred
path — The field path that triggered the error
extensions — Additional metadata, including a machine-readable code

Example: partial error response (HTTP 200)

{
  "data": {
    "playerStats": null
  },
  "errors": [
    {
      "message": "Player not found: 76561198012345678",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "playerStats"
      ],
      "extensions": {
        "code": "NOT_FOUND"
      }
    }
  ]
}

In partnership with

Brilliant game servers for communities large and small.

Get yours today!

A Shrapnelworks product