Error Handling

The Fugoku API uses JSON:API error format for all error responses. Understanding the error structure helps you diagnose and resolve issues quickly.

Error Response Format

All error responses follow this structure:

{
  "errors": [
    {
      "status": "404",
      "code": "NOT_FOUND",
      "detail": "Instance not found"
    }
  ]
}

Error Codes

Common Errors and Resolutions

Instance Not Found (404 / NOT_FOUND)

Cause: The instance ID does not exist or belongs to a different project.

Resolution:

1. Verify the instance ID is correct
2. Check that the instance belongs to your project
3. Ensure the instance has not been deleted

Provider Not Found (404 / PROVIDER_NOT_FOUND)

Cause: The provider ID is invalid, disabled, or not associated with your project.

Resolution:

1. Verify the provider ID exists
2. Check that the provider is enabled
3. Confirm the provider belongs to your project

Invalid Plan (422 / INVALID_PLAN)

Cause: The specified plan does not exist or is not available in the selected region.

Resolution:

1. List available plans: GET /v1/plans
2. Verify the plan slug is correct
3. Check plan availability for the selected region

Invalid Region (422 / INVALID_REGION)

Cause: The specified region/site is not recognized.

Resolution:

1. List available regions: GET /v1/regions
2. Use the correct region identifier

Rate Limited (429)

Cause: Too many requests in a short time period.

Resolution:

1. Check X-RateLimit-Remaining header
2. Wait for the Retry-After duration
3. Implement exponential backoff in your client

Retry Guidance

429 Too Many Requests

• Wait for the duration specified in the Retry-After header
• Retry the request after the wait period
• If rate limited repeatedly, reduce request frequency

5xx Server Errors

• Retry with exponential backoff: 1s, 2s, 4s, 8s, 16s
• Maximum 5 retries
• If all retries fail, contact support

422 Validation Errors

• Fix the request body based on the error details
• Retry immediately (no backoff needed)

401 Unauthorized

• Verify your API token is valid
• Check token expiration
• Re-authenticate if necessary

Request IDs

Every API request generates a unique request ID. Include this ID when contacting support.

Request IDs are returned in response headers and can be used to trace requests through our infrastructure.

Example Error Handling

curl -X POST https://api.fugoku.com/v1/servers \
  -H "Authorization: Bearer $FUGOKU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "servers",
      "attributes": {
        "name": "web-1",
        "site": "invalid-region",
        "plan": "vm-standard",
        "billing": "hourly",
        "role": "VirtualMachine"
      }
    }
  }'

Response (422):

{
  "errors": [
    {
      "status": "422",
      "code": "INVALID_REGION",
      "detail": "Unknown region/site: invalid-region"
    }
  ]
}