Errors



Introduction


The OAuth enabled aID services follows the JSON API standard for error reporting. You can  read about the standard here .

This document describes the details on how we use the JSON API for error reporting. All services can also respond with standard OAuth errors as described in the  OAuth errors section⁠ .

Example response


This is an example of an error response:
{
  "errors": [
    {
      "id": "91c8754b-e253-4dd3-9a5c-2351c0db1d42", 
      "status": "503",
      "code": "general.emergency_mode",
      "title": "Emergency mode enabled",
      "detail": "Emergency mode is currently enabled, we are aware of the problem and working to fix it as soon as possible. In the mean time, most services will be down."
    }
  ]
}

Explanation:
  • id - A Globally unique ID of this instance of the error
  • status - The HTTP response code used for this error (there can be more than one error in a single response).
  • code - A unique code for this type of error. (This is what should be used on caller side to identify a specific error situation.
  • title - Human readable title of this error situation.
  • detail - Human readable details about this instance of the error.

Error codes


All errors have a unique code that can be used to figure out what the error is about. The title and detail text in the error response can change if spelling errors etc. are found, the code will not change in these circumstances. It’s therefore recommended to always use the code when a machine interprets the error response.

The code is built like this:

context(.subcontexts).detail

  • context: The top level context of the error
  • subcontexts: varying number of subcontext levels joined by period.
  • detail: The detail of the current error type

Context

Title
Title
Code
Context
general
General errors relating to the system
request
Errors relating to the request itself, missing parameters etc.
request.parameter
Errors relating to the parameters in the request
request.field
Errors relating to a field posted in a request
request.access
Insuficcient access to perform request
request.access.user
Errors relating to the user who owns an access token
request.access.role
Errors relating to the access role of the application performing the request
request.access.signature
Errors relating to the signature in signed requests
request.access.timestamp
Errors relating to the timestamp in requests requiring timestamp to protect against replay attacks
user
Errors relating to one or more users
group
Errors relating to one or more groups
group.type
Errors relating to a group type (family or company)
group.allotments
Errors relating to a group allotments (max number of members in the group)
group.legal_entity
Errors relating to legal entities in the context of groups
group.user
Errors relating to users in the context of groups
subscription
Errors relating to one or more subscriptions
subscription.source
Errors relating to a subscription source like Infosoft
subscription.connection_type
Errors relating to the connection type between a user and a subscription
publication
Errors relating to one or more publications
publication.not_found
Publication was not found

Detail

Title
Title
Title
Title
Code
HTTP status
Message
Details
general.system_error
500
Internal system error
Something went wrong internally in the aID system. Error was: %s
general.emergency_mode
503
Emergency mode enabled
Emergency mode is currently enabled, we are aware of the problem and working to fix it as soon as possible. In the mean time, most services will be down.
general.not_implemented
400
Not implemented yet
The request requires functionality that has not yet been implemented: %s
request.parameter.missing
400
Required parameter missing in request
parameter=%s
request.field.missing
400
Required field is missing in request
field=%s
request.field.invalid
400
Required field contains invalid value in request
field=%s
request.access.user.not_allowed
403
User is not allowed to perform current request
The user is not allowed to: %s
request.access.role.missing
403
Application does not have access to required role
This endpoint requires that the application has access to role=%s
request.access.signature.invalid
403
Signature does not match request or secret
Provided signature does not match using the application secret and request URL with parameters (included posted fields)
request.access.timestamp.invalid
403
Timestamp not currently valid
Provided timestamp is not valid, current time on server is: %s
request.access.timestamp.invalid.format
400
Timestamp format is invalid
Timestamp must match ISO8601 format, like this: %s
user.deactivated
404
User has been deactivated
The requested user has been deactivated. The user could choose to reactivate in the future, but until then it can not be used.
user.not_found
404
User not found
user.not_found.by_id
404
User not found
No user found with user_id=%s
user.not_found.by_uuid
404
User not found
No user found with uuid=%s
group.not_found
404
Group not found
group.not_found.by_uuid
404
Group not found
No group found with uuid=%s
group.type.not_implemented
400
Support for provided group type is not implemented in the API.
type=%s, valid types are: “company”
group.allotments.too_low
400
Allotment set to lower than current number of members.
allotments=%s is lower than members=%d
group.legal_entity.missing
400
Group or OAuth application is missing legal entity
Legal entity must be set on OAuth applications using group API and groups administrated through the API
group.legal_entity.not_allowed
403
Legal entity is not allowed to perform current request on group
The legal entity is not allowed to: %s
group.user.not_allowed
403
User is not allowed to perform current request on group
The user is not allowed to: %s
subscription.source.unknown
404
Provided subscription source is unknown to the system
source=%s, valid sources are: “infosoft”
subscription.connection_type.unknown
404
Provided connection_type is unknown to the system
connection_type=%s, valid types are “primary” and “secondary”
publication.not_found
404
Publication was not found
publication.not_found.by_domain
404
No publication match domain
No publication found with domain=%s

Common errors

Emergency mode


Sometimes technology behaves very badly. In order to minimize the effect this has on our users, and especially paying customers, we have developed something we call emergency mode.

Emergency mode is manually turned on if we see that something very bad is happening, like a storm of error messages relating to a broken database, or that too many servers are down. When this is turned on, all systems that check access for users will stop caring about who the user is, and what the user has access to, and always try to give the user access to anything the user wants. The effect being that the user can continue reading closed articles and epapers even when the systems needed for checking the user’s subscription is down.

Systems like the login page and My aID will only show an error message telling the user that we are experiencing technical difficulties.

When emergency mode is on, all third party services will respond like this:
{
  "errors": [
    {
      "id": "91c8754b-e253-4dd3-9a5c-2351c0db1d42", 
      "status": "503",
      "code": "general.emergency_mode",
      "title": "Emergency mode enabled",
      "detail": "Emergency mode is currently enabled, we are aware of the problem and working to fix it as soon as possible. In the mean time, most services will be down."
    }
  ]
}

The response code will be 503, and a “Retry-After” header is set indicating that there’s no point retrying before two minutes have passed.

We advice that you use this response to tell the user that something is broken and that someone is working to fix it.