REST API

Errors

The fepli API uses HTTP status codes to say what went wrong, and explains it in a JSON body in the problem details format. The explanation is written for humans and says what to do next.

The error format

Error responses have the content type application/problem+json. The exception is a refused token: that 401 has an empty body and gives its reason in the WWW-Authenticate header.

Name
type
Type
string
Description
A URI reference for the kind of problem, such as /errors/409.
Name
title
Type
string
Description
A short summary. Usually An error occurred.
Name
status
Type
integer
Description
The HTTP status code.
Name
detail
Type
string
Description
What went wrong in this case, and often what to do instead. For validation errors, one line per problem.
Name
violations
Type
array
Description
For malformed input only: one object per problem, with propertyPath, message and code. See Writes.

409 Conflict

{
  "type": "/errors/409",
  "title": "An error occurred",
  "status": 409,
  "detail": "A paid receipt references this application. Reverse the receipt, or withdraw the application instead."
}

Status codes

Name
200 OK
Description
The request succeeded. Also returned by actions such as transitions and reversals.
Name
201 Created
Description
A record was created. The body holds it.
Name
202 Accepted
Description
The request was accepted, and the work finishes in the background, as when refilling a waiting list or unblocking an e-mail address. The body shows the record as it is now; fetch it again a little later to see the result.
Name
204 No Content
Description
A record was deleted.
Name
400 Bad Request
Description
A query parameter can't be read, such as a malformed date, a boolean that isn't true or false, or an unknown application status. The detail names the parameter. Fix the request; retrying won't help.
Name
401 Unauthorized
Description
No valid token: it is malformed, unknown or expired, or its owner is disabled. The body is empty; see the WWW-Authenticate header. Also returned for anonymous requests to anything other than the public offers. See Authentication.
Name
403 Forbidden
Description
The token is valid but may not do this: it is read-only and the request writes, or its owner lacks the role or the permission for this action, for example an organiser changing a published offer. The detail usually says why.
Name
404 Not Found
Description
The record doesn't exist, or you may not see it. The API doesn't tell these apart. Also returned when the API is switched off for the municipality.
Name
409 Conflict
Description
The action doesn't fit the record's current state: a transition that isn't possible right now, deleting something a paid receipt still refers to, paying an application twice. The detail says what is possible instead.
Name
415 Unsupported Media Type
Description
A request body was sent without Content-Type: application/json.
Name
422 Unprocessable Entity
Description
The request body is invalid: a required field is missing, a value is out of range, or a referenced record doesn't exist. One line per problem in detail.
Name
429 Too Many Requests
Description
You hit the rate limit. Wait before you retry.
Name
500 Internal Server Error
Description
Something went wrong on the server. Retry later. If it persists, contact support with the time and the request.

Examples

Error responses

{
  "type": "/errors/400",
  "title": "An error occurred",
  "status": 400,
  "detail": "Unknown status \"paid\". Known: waiting, confirmed, waitlisted, rejected, withdrawn, unfulfilled, participated, noshow, email_unconfirmed, consents_outstanding."
}

Handling errors

4xx except 429: don't retry the same request. Read detail, fix the request or the data, then try again.
409: fetch the record again. Its transitions, status or paid flag tells you what is possible now.
429 and 5xx: retry with an increasing delay, for example after 1, 2, 4 and 8 seconds.
Log detail along with the status. It is the fastest way to understand what happened.