Error Handling

All API errors include an HTTP status code, a unique error code, and a descriptive message. This guide documents all possible errors that can occur when interacting with our APIs.

⚠️

Note: The Core API uses OAuth 2.0 compliant error responses, which have a different structure than the standard format. See the response format sections below for details.

Standard Error Response

All APIs except Core use the following error response structure:

{
    "timestamp": "2024-01-15T10:30:00.000Z",
    "moreInfo": "https://docs.neobits.no/",
    "errors": [
        {
            "name": "BadRequestError",
            "code": "400-001",
            "message": "Field 'ssn' is required"
        }
    ]
}

timestamp - ISO 8601 formatted date and time when the error occurred
moreInfo - URL to the documentation for more information
errors - Array of error objects containing:

name - The error type identifier
code - A unique error code in the format HTTP_STATUS-SEQUENCE
message - A human-readable description of the error

OAuth 2.0 Error Response (Core API)

The Core API follows the OAuth 2.0 specification for error responses:

{
    "error": "invalid_request",
    "error_code": "400-001",
    "error_uri": "https://docs.neobits.no/",
    "error_description": "Field 'client_id' is required",
    "error_timestamp": "2024-01-15T10:30:00.000Z"
}

error - OAuth 2.0 error code (e.g., invalid_request, unauthorized, access_denied)
error_code - A unique error code in the format HTTP_STATUS-SEQUENCE
error_uri - URL to the documentation for more information
error_description - A human-readable description of the error
error_timestamp - ISO 8601 formatted date and time when the error occurred

Error Types by HTTP Status Code

400

BadRequest

The request was invalid or malformed. This typically occurs due to validation errors, missing required fields, or invalid field values.

Code	Code Name	Description	APIs
400-000	BadRequest	Generic bad request error	FuseCore
400-001	FieldRequired	A required field is missing from the request	FuseCore
400-002	FieldUnknown	An unknown or unexpected field was provided	FuseCore
400-003	FieldValueInvalid	The field value is invalid or not allowed	FuseCore
400-004	FieldTypeInvalid	The field type does not match the expected type	FuseCore
400-005	FieldValueEmpty	The field value is empty when a value is required	FuseCore
400-006	ResourceAlreadyExists	The resource being created already exists	Fuse
400-007	FeatureNotEnabled	The requested feature is not enabled for your account	Fuse
400-008	Unknown	An unknown bad request error occurred	FuseCore
400-100	PasswordWeak	The password does not meet security requirements	Core
400-101	PasswordTooShort	The password is too short	Core
400-102	InvalidEmail	The email address format is invalid	FuseCore
400-103	InvalidUri	The URI format is invalid	FuseCore
400-104	InvalidUuid	The UUID format is invalid	FuseCore
400-105	InvalidLength	The field length does not meet requirements	FuseCore
400-106	InvalidPattern	The field does not match the required pattern	FuseCore
400-107	InvalidFormat	The field format is invalid	FuseCore
400-108	InvalidCodeChallenge	The PKCE code challenge is invalid	Core
400-109	InvalidCodeChallengeMethod	The PKCE code challenge method is invalid	Core
400-110	InvalidAuthorizationCode	The authorization code is invalid	Core
400-111	AuthorizationCodeExpired	The authorization code has expired	Core
400-112	AuthorizationCodeAlreadyUsed	The authorization code has already been used	Core

401

Unauthorized

Authentication is required but was not provided or is invalid. Verify your credentials and try again.

Code	Code Name	Description	APIs
401-000	Unauthorized	Generic unauthorized error - client is not authenticated	FuseCore
401-001	InvalidCredentials	The provided credentials are invalid	FuseCore
401-002	InvalidToken	The authentication token is invalid or expired	FuseCore
401-003	AccountLocked	The account has been locked due to security reasons	Core
401-004	AccountDisabled	The account has been disabled	Core
401-005	EmailNotVerified	The email address has not been verified	Core
401-006	ClientDisabled	The API client has been disabled	FuseCore
401-007	InvalidAuthorizationFlow	The authorization flow is invalid or not supported	Core

403

Forbidden

The authenticated user does not have permission to access the requested resource.

Code	Code Name	Description	APIs
403-000	Forbidden	Generic forbidden error - access denied	FuseCore
403-001	InsufficientPermissions	The user lacks the required permissions for this action	FuseCore

404

NotFound

The requested resource could not be found. Verify the resource identifier and try again.

Code	Code Name	Description	APIs
404-000	NotFound	Generic not found error	FuseCore
404-001	Resource	The requested resource does not exist	FuseCore
404-002	Upstream	The resource was not found in an upstream service	Fuse

409

Conflict

The request conflicts with the current state of the resource.

Code	Code Name	Description	APIs
409-000	Conflict	Generic conflict error	FuseCore
409-001	ResourceAlreadyExists	A resource with the same identifier already exists	FuseCore
409-002	StateMismatch	The resource state does not allow this operation	Fuse

422

UnprocessableContent

The request was well-formed but the content could not be processed.

Code	Code Name	Description	APIs
422-000	UnprocessableContent	Generic unprocessable content error	Fuse
422-001	UpstreamResponseUnsupported	The response from an upstream service is not supported	Fuse

429

TooManyRequests

The rate limit has been exceeded. Wait before making additional requests.

Code	Code Name	Description	APIs
429-000	TooManyRequests	Rate limit exceeded - please try again later	FuseCore

500

InternalServerError

An unexpected error occurred on the server. If the problem persists, please contact support.

Code	Code Name	Description	APIs
500-000	InternalServer	An unexpected internal error occurred	FuseCore
500-001	Configuration	A server configuration error occurred	FuseCore

502

BadGateway

An upstream service returned an error response. This is typically a temporary issue.

Code	Code Name	Description	APIs
502-000	BadGateway	Error while interacting with a third party service	Fuse
502-001	ConnectionAborted	The connection to an upstream service was aborted	Fuse

503

ServiceUnavailable

The service is temporarily unavailable. Retry after a short delay.

Code	Code Name	Description	APIs
503-000	ServiceUnavailable	The service is temporarily unavailable. Retry after a short delay.	Fuse

504

GatewayTimeout

The request timed out while waiting for an upstream service.

Code	Code Name	Description	APIs
504-000	GatewayTimeout	Gateway timeout while waiting for an upstream service	Fuse

Best Practices for Error Handling

Check the error code - Use the error code to programmatically handle specific error scenarios. The code is stable and will not change without prior notice.
Log errors for debugging - Include the full error response in your logs, especially the timestamp and error code fields.
Implement retry logic - For 5xx errors and 429 errors, implement exponential backoff retry logic.
Display user-friendly messages - Use the error message field to display human-readable error messages to end users.
Contact support if needed - If you encounter persistent 500 errors, contact our support team with the error details and timestamp.