Errors

A request that fails gets an HTTP status from 400 up and a body with an error object, and nothing else.

The error object#

JSON

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "limit must be 1 to 100.",
    "param": "limit",
    "doc_url": "https://developer.welly.no/docs/errors#parameter_invalid",
    "request_id": "req_6b1d0c9e2f4a4d1c"
  }
}

Field	Meaning
`type`	The kind of error, for your first branch. One of the five below.
`code`	The exact reason. Stable: we never change what a code means.
`message`	What went wrong, for people. It may change, so do not match on it.
`param`	The parameter the error is about, or `null`.
`doc_url`	This page, at the code's row.
`request_id`	The same id as the `Welly-Request-Id` header.

Types#

Type	Status	What to do
`invalid_request_error`	400, 404, 405, 409	Fix the request. Trying again unchanged gives the same answer.
`authentication_error`	401	Check the key you send.
`permission_error`	403	The key may not do this. Ask us if it should.
`rate_limit_error`	429	Wait the seconds in `Retry-After`, then try again.
`api_error`	500, 503	Our fault. Try again with a pause; send us the request id if it lasts.

Codes#

New codes may come. Treat a code you do not know by its type.

Code	Status	Type	Meaning
`parameter_missing`	400	`invalid_request_error`	A required parameter is missing.
`parameter_invalid`	400	`invalid_request_error`	A parameter has a value that is not allowed.
`parameter_unknown`	400	`invalid_request_error`	A parameter is not known for this endpoint.
`body_invalid`	400	`invalid_request_error`	The request body is not valid JSON.
`resource_missing`	404	`invalid_request_error`	No such resource.
`method_not_allowed`	405	`invalid_request_error`	This method is not allowed here.
`conflict`	409	`invalid_request_error`	The request conflicts with the current state.
`key_missing`	401	`authentication_error`	No API key was sent.
`key_invalid`	401	`authentication_error`	The API key is not valid.
`key_revoked`	401	`authentication_error`	The API key has been revoked.
`permission_denied`	403	`permission_error`	This key may not do this.
`mode_mismatch`	403	`permission_error`	A test key cannot reach live data, nor a live key test data.
`rate_limited`	429	`rate_limit_error`	Too many requests. Wait for the time in Retry-After.
`internal_error`	500	`api_error`	An internal error occurred.
`unavailable`	503	`api_error`	The API is down for maintenance. Try again shortly.

Server errors#

A server error never says what went wrong inside the API; its message is always the same. The request id is how we find it, so log it and send it to us.