Shared Responses

These may show up on any given route in any service.

The content of error is unreliable, use code instead. See Error Codes for a full list.

Invalid API Key

401 Unauthorized

{
  "success": false,
  "error": "Invalid api key.",
  "code": 1010
}

API Key Is Inactive

401 Unauthorized

{
  "success": false,
  "error": "Api key is inactive.",
  "code": 1011
}

API Key Disabled

403 Forbidden

{
  "success": "false",
  "error": "Your api key has been disabled by an administrator. See \"extra.reason\" for the reasoning.",
  "extra": {
    "reason": "",
    "support": "https://yiff.rest/support"
  },
  "code": 1012
}

Bad User Agent

403 Forbidden

// Reasons:
// Bots are not allowed to crawl our api.
// This is a default library user agent, and does not give us any information about the client making the request. Please set an informative user agent.
// The user agent you supplied is non-informative, it's likely just one word or something meaningless. Please provide actual client info in your user agent.
// You did not supply a user agent. You need to supply one with valid client information.
// This user agent has been blocked for spamming our api. Don't do that.
{
  "success": false,
  "error": "Your user agent has been blocked. See \"extra\" for the reasoning.",
  "extra": {
    "reason": "(see top)",
    "help": "https://yiff.rest/support"
  },
  "code": 1021
}

No Access To Service

403 Forbidden

{
  "success": false,
  "error": "You do not have access to this service.",
  "code": 1022
}

Unknown API Route

404 Not Found

{
  "success": false,
  "error": "Unknown api route.",
  "code": 1024
}

Rate Limited

429 Too Many Requests

// global headers will also be present
{
  "success": false,
  "error": "Request Limit Exceeded",
  "code": 1000,
  "info": {
    "limit": 0, // X-RateLimit-Limit
    "remaining": 0, // X-RateLimit-Remaining
    "reset": 0, // X-RateLimit-Reset
    "resetAfter": 0, // X-RateLimit-Reset-After
    "retryAfter": 0, // Retry-After
    "bucket": "", // X-RateLimit-Bucket
    "precision": "millisecond", // X-RateLimit-Precision
    "global": false
  }
}

Globally Rate Limited

429 Too Many Requests

// route specific headers will also be present
{
  "success": false,
  "error": "Request Limit Exceeded",
  "code": 1001,
  "info": {
    "limit": 0, // X-RateLimit-Global-Limit
    "remaining": 0, // X-RateLimit-Global-Remaining
    "reset": 0, // X-RateLimit-Global-Reset
    "resetAfter": 0, // X-RateLimit-Global-Reset-After
    "retryAfter": 0, // Retry-After
    "bucket": null,
    "precision": "millisecond", // X-RateLimit-Global-Precision
    "global": true
  }
}

Read Only

503 Service Unavailable

{
  "success": false,
  "error": "Service is currently in read-only mode.",
  "code": 2
}

Server Disk Full

507 Insufficient Storage

{
  "success": false,
  "error": "Internal disk is full, try again later.",
  "code": 1020
}