Err on Side Of Whimsy

Man approaches the unattainable truth through a succession of errors. - Aldous Huxley

http POST https://dash.readme.com/api/v1/api-spec/8ask23jlkasdf
 
{
"code": "SPEC_NOT_FOUND",
"message": "The spec you specified (8ask23jlkasdf) doesn't match any of the existing ones in ReadMe",
"suggestion": "Your spec id is a 12-digit code that you can find in the API Reference section of the ReadMe dashboard.",
"poem": [
"We couldn't find your spec",
"But we found other things instead!",
"Like change in the couch cushion",
"And a monster under the bed"
]
}
 
404 Not Found
http POST https://dash.readme.com/api/v1/
 
{
"code": "PROJECT_EMPTY",
"message": "You must provide a project to log in to",
"suggestion": "Pass in a project via the `project` body param. You can find a list of projects in your ReadMe dashboard!",
"poem": [
"Like a private speakeasy",
"Asking for a password at the door",
"We require you to tell us a project",
"Before you can see more"
]
}
 
400 Bad Request
http POST https://dash.readme.com/api/v1/
 
{
"code": "LOGIN_TWOFACTOR",
"message": "You must provide a two-factor code",
"suggestion": "You can do it via the API using `token`, or via the CLI using `rdme login --2fa`",
"poem": [
"Two-factor makes you safer",
"But now logins make you groan",
"Anytime you want to use a site",
"You have to pull out your phone"
]
}
 
401 Unauthorized
http POST https://dash.readme.com/api/v1/version/1.0.0
 
{
"code": "VERSION_CANT_DEMOTE_STABLE",
"message": "You can't make a stable version non-stable",
"suggestion": "There must be one stable version at all times. So, rather than demoting this version, promote another version (1.0.0, 2.0.0, 2.0.1) to be the stable version and this version will automatically not be stable.",
"poem": [
"The aliens arrived one day",
"'To your documentation, we shall go'",
"But because none of your docs were stable",
"We weren't sure which version to show"
]
}
 
400 Bad Request
http PUT https://dash.readme.com/api/v1/this-doesnt-exist
 
{
"code": "UNKNOWN_ENDPOINT",
"message": "The endpoint you called (PUT /api/v1/this-doesnt-exist) doesn't exist",
"suggestion": "You can view all our available endpoints in our docs (https://docs.readme.com/developers/reference/)",
"poem": [
"'Not all those who wander are lost'",
"Wow, that's quite profound!",
"Except… this time you're certainly adrift",
"Because this endpoint is 404 Not Found"
]
}
 
404 Not Found
http POST https://dash.readme.com/api/v1/api-spec/8ask23jlkasdf
 
{
"code": "INVALID_SPEC_ID",
"message": "The spec id you sent (8ask23jlkasdf) isn't a valid spec id",
"suggestion": "Spec IDs must be a 12-digit OID. If it's an existing spec, you can find the valid value in the API Reference section of the ReadMe dashboard.",
"poem": [
"You tried to slip one by us",
"But don't take us for fools!",
"We require a valid OID",
"And yours doesn't fit the rules"
]
}
 
400 Bad Request
http POST https://dash.readme.com/api/v1/
 
{
"code": "APIKEY_EMPTY",
"message": "You must pass in an API key",
"suggestion": "API keys can be passed in as the username part of basic auth. You can find a code snippet in our docs! You can get your API key in Configuation > API Key, or in the docs.",
"poem": [
"A very little key",
"Can open a heavy door",
"So include your authenticaion",
"To see what our API has in store!"
]
}
 
401 Unauthorized
http POST https://dash.readme.com/api/v1/version/1.0.0
 
{
"code": "VERSION_CANT_REMOVE_STABLE",
"message": "You can't delete the main 'stable' version of your API",
"suggestion": "To remove this version (3.0.3), set 'stable: true' for an existing version (1.0.0, 2.0.0, 2.0.1) first.",
"poem": [
"The time is up for this old version",
"But when vanquishing it, you're not able",
"Turns out you can't remove a version",
"While it is still marked as 'stable'"
]
}
 
400 Bad Request
http POST https://dash.readme.com/api/v1/changelog/test
 
{
"code": "CHANGELOG_NOT_FOUND",
"message": "The changelog with the slug 'test' couldn't be found",
"suggestion": "This is for changelogs. If you're trying to upload a doc or reference guide, those are different endpoints!",
"poem": [
"If a tree falls in the forest",
"Is there quiet in the air?",
"If a feature isn't in the changelog",
"Is it even really there?"
]
}
 
404 Not Found
http POST https://dash.readme.com/api/v1/version/1.0.3
 
{
"code": "VERSION_FORK_NOT_FOUND",
"message": "We couldn't find the version (3.0.3) you're trying to fork from.",
"suggestion": "You need to pass an existing version (1.0.0, 2.0.0, 2.0.1) in via the `for` parameter",
"poem": [
"This request unfortunately failed",
"But hey, I guess that's life",
"We couldn't find your version fork",
"Or your version spoon or version knife"
]
}
 
404 Not Found
http POST https://dash.readme.com/api/v1/
 
{
"code": "APIKEY_NOT_FOUND",
"message": "We couldn't find your API key",
"suggestion": "The API key you passed in (k92ry········328) doesn't match any keys we have in our system. API keys must be passed in as the username part of basic auth. You can get your API key in Configuation > API Key, or in the docs.",
"poem": [
"The ancient gatekeeper declares:",
"'To pass, reveal your API key'",
"'k92ry…', you start to ramble",
"Oops, you remembered it poorly!"
]
}
 
401 Unauthorized
http POST https://dash.readme.com/api/v1/doc/test
 
{
"code": "DOC_NOT_FOUND",
"message": "The doc with the slug 'test' couldn't be found",
"suggestion": "Make sure you have the slug correct! It should look something like `getting-started`. Slugs can be changed, so it's possible someone moved it!",
"poem": [
"The greatest trick the devil pulled",
"Was convincing us he doesn't exist",
"This doc isn't nearly that clever…",
"It's just simply gone amiss"
]
}
 
404 Not Found
http POST https://dash.readme.com/api/v1/
 
{
"code": "LOGIN_INVALID",
"message": "Either your email address or password is incorrect",
"suggestion": "You can reset your password at https://dash.readme.com/forgot",
"poem": [
"I can't remember if it's 'hunter1'",
"Or 'password1234'?",
"I wish I wrote it down somewhere",
"Because memorizing is such a chore"
]
}
 
401 Unauthorized
http POST https://dash.readme.com/api/v1/
 
{
"code": "APIKEY_MISMATCH",
"message": "The API key doesn't match the project",
"suggestion": "Your project exists and your API key is valid… but they don't match! It's likely you're trying to use the same API key for multiple projects. Each project has its own API key, which you can get in the dashboard from Configuration > API Key.",
"poem": [
"Shoes and socks, wine and cheese",
"Peanut butter and jelly",
"These things all go together well",
"Unlike this project and API key"
]
}
 
403 Forbidden
http POST https://dash.readme.com/api/v1/
 
{
"code": "LOGIN_TWOFACTOR_INVALID",
"message": "Your two-factor code is wrong",
"suggestion": "The two-factor code you entered is incorrect. If you need help, you can contact our support team!",
"poem": [
"Grab your Authenticator",
"You'll need it to unlock",
"Hurry, the code won't last forever",
"It's a race against the clock"
]
}
 
401 Unauthorized
http GET https://dash.readme.com/api/v1/doc/test
 
{
"code": "VERSION_EMPTY",
"message": "You need to include an x-readme-version header",
"suggestion": "Try passing in an existing version (1.0.0, 2.0.0, 2.0.1) in the x-readme-version header. The version in the URL is our API version, not the version of of your docs.",
"poem": [
"Seems you left out the version",
"And we don't want to have to guess",
"We want to serve you the right thing",
"And figuring it out is too much stress!"
]
}
 
400 Bad Request
http GET https://dash.readme.com/api/v1/doc/test
 
{
"code": "VERSION_NOT_FOUND",
"message": "The version you specified (3.0.3) doesn't match any of the existing versions (1.0.0, 2.0.0, 2.0.1) in ReadMe.",
"suggestion": "You can pass the version in via the `x-readme-version` header. If you want to create a new version, do so in the Versions section inside ReadMe. Note that the version in the URL is our API version, not the version of of your docs.",
"poem": [
"We looked high and low",
"Searched up, down and around",
"You'll have to give it another go",
"Because version 3.0.3's not found!"
]
}
 
404 Not Found
http GET https://dash.readme.com/api/v1/api-spec/8ask23jlkasdf
 
{
"code": "SPEC_VERSION_NOT_FOUND",
"message": "The version you specified (3.0.3) doesn't match any of the existing versions (1.0.0, 2.0.0, 2.0.1) in ReadMe.",
"suggestion": "You can pass the version in either in your OAS file in info.version, or override it with an x-readme-version header. Note that the version in the URL is our API version, not the version of of your docs.",
"poem": [
"I noticed some irregularities",
"And the difference made me think",
"So after a bit exploration",
"It appears they're out of sync!"
]
}
 
400 Bad Request
http POST https://dash.readme.com/api/v1/version/1.0.3
 
{
"code": "VERSION_FORK_EMPTY",
"message": "New versions need to be forked from an existing version.",
"suggestion": "You need to pass an existing version (1.0.0, 2.0.0, 2.0.1) in via the `for` parameter",
"poem": [
"When creating a new version",
"A `for` value must be attached",
"You'll have to start from somewhere",
"Since versions can't start from scratch"
]
}
 
400 Bad Request
http POST https://dash.readme.com/api/v1/version/1.0.3
 
{
"code": "VERSION_DUPLICATE",
"message": "Version 3.0.3 already exists",
"suggestion": "Because they already exist, you can't create the following versions: 1.0.0, 2.0.0, 2.0.1. We normalize semver, so 1.0 and 1.0.0 count as the same thing.",
"poem": [
"Two scoops of ice cream are better than one",
"And two cookies are quite the perk",
"But two of the same version",
"Simply will not work!"
]
}
 
400 Bad Request
http GET https://dash.readme.com/api/v1/project/test-project
 
{
"code": "PROJECT_NOT_FOUND",
"message": "The project (test-project) can't be found",
"suggestion": "The project is referred to as your `subdomain` in the dashboard when you're looking for it. If you're sure it exists, maybe you don't have access to it? You can check if it exists here: https://test-project.readme.io",
"poem": [
"You told us the project you wanted",
"Unfortunately we can't find this",
"But think of the possibilities ahead of you…",
"There's nothing like a blank canvas!"
]
}
 
404 Not Found
http POST https://dash.readme.com/api/v1/api-spec/8ask23jlkasdf
 
{
"code": "SPEC_FILE_EMPTY",
"message": "You need to include a spec file",
"suggestion": "You'll need to upload a valid Swagger/OAS file (either JSON or YAML) via the `spec` parameter to this endpoint for it to work.",
"poem": [
"Usually API calls go smoothly",
"But this time it did not",
"Our endpoint requires a spec",
"And it seems that you forgot"
]
}
 
400 Bad Request
http POST https://dash.readme.com/api/v1/api-spec/8ask23jlkasdf
 
{
"code": "INVALID_SPEC",
"message": "The spec you uploaded isn't a valid JSON or YAML file. Here's the error we found: Page title cannnot be blank",
"suggestion": "Try running your spec through a validator to see if they pick up any issues with the formatting!",
"poem": [
"When we asked for your swagger",
"It seems you misunderstood",
"You sent us a cool attitude",
"Instead some JSON would have been good"
]
}
 
400 Bad Request
http POST https://dash.readme.com/api/v1/version/1.0.0
 
{
"code": "VERSION_INVALID",
"message": "This version is invalid (Page title cannnot be blank)",
"suggestion": "The version you used isn't a valid version. Versions must be semver (it'll look something like '1.2.1'). Try using one of your existing versions (1.0.0, 2.0.0, 2.0.1).",
"poem": [
"You walk into the diner",
"And ask if they have stew",
"The waitress rolls her eyes",
"'Please stick to the menu'"
]
}
 
400 Bad Request
http POST https://dash.readme.com/api/v1/category/test
 
{
"code": "CATEGORY_NOT_FOUND",
"message": "The category with the slug 'test' couldn't be found",
"suggestion": "You can list all available categories using GET /api/v1/categories",
"poem": [
"All your docs are organized",
"Into thoughtful little categories",
"But this one we can't quite find",
"I'm so sorry to displease!"
]
}
 
404 Not Found
http POST https://dash.readme.com/api/v1/api-spec/8ask23jlkasdf
 
{
"code": "SPEC_TIMEOUT",
"message": "Your import timed out after 10 seconds",
"suggestion": "Try breaking it up into smaller chunks, or contact support@readme.io. This usually doesn't happen because of file size, but rather too make circular $refs.",
"poem": [
"We're resolving your $refs",
"Hurry up, double the pace!",
"Drats! Not fast enough",
"We got a stack trace"
]
}
 
400 Bad Request
http POST https://dash.readme.com/api/v1/page/test
 
{
"code": "CUSTOM_PAGE_NOT_FOUND",
"message": "The custom page with the slug 'test' couldn't be found",
"suggestion": "This is for custom pages. If you're trying to upload a doc or reference guide, those are different endpoints!",
"poem": [
"Custom pages are where you can go crazy",
"It's up to you how they are styled",
"But it seems this one isn't created yet",
"So time to let your mind go wild!"
]
}
 
404 Not Found
http POST https://dash.readme.com/api/v1/page/test
 
{
"code": "INVALID_CUSTOM_PAGE_FORMAT",
"message": "We couldn't save this page (Page title cannnot be blank)",
"suggestion": "Make sure all the data is correct, and the body is valid Markdown or HTML.",
"poem": [
"We had trouble saving this",
"Which is quite a shame",
"I'm not sure whose fault it is",
"If your boss asks, I'll take the blame"
]
}
 
400 Bad Request
http POST https://dash.readme.com/api/v1/changelog/test
 
{
"code": "INVALID_CHANGELOG_FORMAT",
"message": "We couldn't save this changelog (Page title cannnot be blank)",
"suggestion": "Make sure all the data is correct, and the body is valid Markdown.",
"poem": [
"The changelog is for denoting",
"What has changed and what is kept",
"But the one thing that hasn't changed",
"Is the format of data we accept"
]
}
 
400 Bad Request
http POST https://dash.readme.com/api/v1/doc/test
 
{
"code": "INVALID_DOC_FORMAT",
"message": "We couldn't save this doc (Page title cannnot be blank)",
"suggestion": "Make sure all the data is correct, and the body is valid Markdown.",
"poem": [
"We do our best to understand",
"Any documentation coming inbound",
"Seems you sent an invalid value",
"Or maybe some mucked-up markdown?"
]
}
 
400 Bad Request
http POST https://dash.readme.com/api/v1/
 
{
"code": "INTERNAL_ERROR",
"message": "Unknown error (Page title cannnot be blank)",
"suggestion": "Sorry this error isn't more helpful… if you're seeing this, we're stumped too! But email support (support@readme.io) and we can figure it out with you.",
"poem": [
"If you're seeing this error",
"Something went wrong internally",
"This error is our catch-all",
"It's one you should never see!"
]
}
 
Server Error