API Reference

Error Handling

Understand API error responses, error codes, and how to handle them in your integrations.

Error Response Format

When an API request fails, the response body contains a structured error object:

Error Response Structurejson

{
  "error": {
    "code": "not_found",
    "message": "Tournament not found",
    "details": []
  }
}

Field	Type	Description
`code`	`string`	Machine-readable error code (use this for programmatic handling)
`message`	`string`	Human-readable description of the error
`details`	`array`	Additional error details (e.g., field-level validation errors)

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of a request:

Success Codes

Status	Meaning	When
`200`	OK	Request succeeded (GET, DELETE)
`201`	Created	Resource was successfully created (POST)

Client Error Codes

Status	Meaning	When
`400`	Bad Request	Invalid request body, missing required fields
`401`	Unauthorized	Missing, invalid, revoked, or expired API key
`403`	Forbidden	API key lacks the required scope for this endpoint
`404`	Not Found	Resource does not exist or you don't have access
`422`	Unprocessable Entity	Validation failed — check the `details` array
`429`	Too Many Requests	Rate limit exceeded — wait and retry

Server Error Codes

Status	Meaning	When
`500`	Internal Server Error	Something went wrong on our end

Error Codes Reference

The code field in error responses uses these machine-readable identifiers:

Code	HTTP	Description
`unauthorized`	401	Missing, invalid, expired, or revoked API key
`forbidden`	403	API key does not have the required permission scope
`not_found`	404	Resource does not exist or is not accessible to this key
`validation_error`	422	Request body failed validation
`rate_limit_exceeded`	429	Too many requests in the current window
`key_limit_reached`	400	Maximum of 10 active API keys per account
`database_error`	500	Internal database error (contact support if persistent)
`internal_error`	500	Unexpected server error

Validation Errors

When a request body fails validation (422), the details array contains field-level errors:

422 Validation Errorjson

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": [
      {
        "field": "name",
        "message": "String must contain at least 1 character(s)"
      },
      {
        "field": "permissions",
        "message": "Array must contain at least 1 element(s)"
      }
    ]
  }
}

Tip

Always check the details array for validation errors. Each entry includes the field name and a descriptive message.

Handling Errors

Here's a recommended pattern for handling API errors:

Error Handling Examplejavascript

async function callApi(path, options = {}) {
  const res = await fetch(`https://readyraider.com/api/v1${path}`, {
    ...options,
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  const body = await res.json();

  if (!res.ok) {
    const error = body.error;
    switch (error.code) {
      case "unauthorized":
        throw new Error("Invalid API key. Check your credentials.");
      case "forbidden":
        throw new Error(`Missing scope: ${error.message}`);
      case "not_found":
        return null; // Resource not found
      case "rate_limit_exceeded":
        const retryAfter = res.headers.get("Retry-After");
        throw new Error(`Rate limited. Retry after ${retryAfter}s`);
      case "validation_error":
        const fields = error.details.map(d => `${d.field}: ${d.message}`);
        throw new Error(`Validation failed: ${fields.join(", ")}`);
      default:
        throw new Error(`API error: ${error.message}`);
    }
  }

  return body.data;
}

Troubleshooting

Getting 401 on every request?

Verify your API key starts with rr_live_ and that you're using Bearer (not Basic) in the Authorization header. Also check that the key hasn't been revoked or expired.

Getting 403 Forbidden?

The error message will tell you which scope is required. Create a new API key with the needed scope, or check that your existing key has the right permissions.

Getting 404 for a resource you know exists?

The API returns 404 for both "not found" and "no access" to prevent resource enumeration. Verify you have the correct ID and that the resource is accessible to the authenticated user.

Getting 500 errors?

Include the X-Request-Id header value when contacting support. This helps us trace the exact request that failed.

PreviousRate Limits

NextTournaments API