# Error Responses All errors (4xx and 5xx) response bodies wrap in an “error” structure containing: * `code` (the numeric error code; e.g., 401, 402, etc.). * `title` (the name of the error; e.g., Bad Request, Unauthenticated, etc.). * `detail` (a description providing additional information; e.g., Access token was not provided or not recognized). For example: ``` `{ "error": { "code": 403, "title": "Unauthorized Access", "detail": "Access token was not provided or not recognized." } }` ``` Some errors include additional data fields containing information about the error. For example, a validation error will contain a `validations` field as shown below: ``` `{ "error": { "code": 400, "title": "Bad Request", "detail": "One or more request validations have failed. The request cannot be completed unless all validations are passed.", "validations": [ { "code": "required", "detail": "Title is required", "parameter": "title" } ] } }` ``` ## Client Error Codes A request parameter or formatting does not match an expected required format. Error codes in the range 400 - 499 indicate invalid input or improper use of the API. Clients should alter their request to correct the indicated error before trying the request again. ### 400 **Bad Request** A request parameter or formatting does not match an expected required format. Typical cases include: * Missing a required parameter. * Invalid formatting of a parameter (e.g., numerical value where text is expected, incorrect or invalid enum) * Timestamp filter where the parameter value cannot be coerced to a date or time. * Incorrect query or path parameter, invalid page size number, text instead of a numerical value, etc. * Page number or size is not in valid range. * Validation errors include an additional `validations` parameter that contains an array of validation entries specific to individual parameters in the request. **Feeds Example** Sending an incorrect query value with a GET results in a 400. This example shows the Return a user's feed of posts endpoint throwing an error. The `name` query parameter does not include one of the supported enum options of: `"myfeed"`, `"following"`, `"resources"`, `"trending"`, `"icymi"`, `"featured"`, `"bookmarked"`, `"community_images"`. ``` { "error": { "code": 400, "title": "Bad Request", "detail": "One or more request validations have failed. The request cannot be completed unless all validations are passed.", "validations": [ { "rule": "invalid_enum", "parameter": "name", "message": "name must be one of: myfeed, following, resources, trending, icymi, featured, bookmarked, community_images" } ] } } ``` **Content Examples** This example shows the List all topics in the program endpoint throwing an error. The `state` query parameter does not include one of the supported enum options of: `"archived"`, `"hidden"`, `"published"`, `"any"`. ``` { "error": { "code": 400, "title": "Bad Request", "detail": "One or more request validations have failed. The request cannot be completed unless all validations are passed.", "validations": [ { "rule": "invalid_enum", "parameter": "state", "message": "state must be one of archived, hidden, published, any" } ] } } ``` This example shows the create content endpoint throwing an error. Here, multiple validations are incorrect from the request body: * An incorrect enum type was passed from the `content_type` parameter. The available enum validations are: `"article"`, `"link"`, `"video"`, `"image"`. * The `user_id` was not a numerical value from the `author` object. * An invalid `timestamp` was passed (needs to be ISO 8601 format and are expressed in the UTC timezone.) ``` { "error": { "code": 400, "title": "Bad Request", "detail": "One or more request validations have failed. The request cannot be completed unless all validations are passed.", "validations": [ { "rule": "invalid_enum", "parameter": "content_type", "message": "content_type is invalid" }, { "rule": "numeric", "parameter": "user_id", "message": "user_id is invalid" }, { "rule": "invalid_timestamp_or_datestamp", "parameter": "posted_at", "message": "posted_at is invalid" } ] } } ``` **Users Example** This example shows the List users in the program endpoint throwing an error. The filter has not been used correctly. `username is frank` is not the supported format. ``` { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:Error" ], "status": 400, "detail": "Validation failed: filter operation not supported: .", "scimType": "invalidFilter" } ``` The correct format just needs a username (or a section of a username); `eq frank` or just `frank` (provided there is an existing username with frank). Refer to our user names section for more guidance. ### 401 **Unauthenticated** Returned when a required access token is not provided. Check: * You are connected to the correct authentication server: * US1: https://auth.socialchorus.com * US2: https://auth.us2.onfirstup.com * EU: https://auth.onfirstup.eu * You are using the correct authentication method. Endpoints like Feeds require authorization as a user, endpoints like Content require authorization as a serer. Find the **Security** section in each endpoint's documentation to see the required auth method. * Your session is still active. Access tokens expire after 2 hours. Authorization codes expire in 10 minutes. See Authentication and Authorization for details. **Example** ``` { "error": { "code": 401, "title": "Unauthenticated", "detail": "Access token was not provided or not recognized." } } ``` ### 403 **Forbidden** The Authenticated User does not have permissions required to perform the action requested. Check: * The **Security** section in each endpoint's documentation to see the required scopes. See Auth Scope List and Definitions for details. * You have the same (or higher) permissions or role as the user(s) you are attempting to get, create or edit with the Users endpoints. **Example** This example shows a user attempting to perform a PATCH request on another user account with a role higher to their own. Role updates require the acting user's role to be the same or higher role than the user being updated both before and after the role update ``` { "schemas": [ "urn:ietf:params:scim:api:messages:2.0:Error" ], "status": 403, "detail": "The authenticated user does not have permission to perform the requested action." } ``` ### 404 **Not Found** Returned when a primary resource is not found. A primary resource can be defined as resource scoped in the URL of the endpoint. **Examples** * `GET /content/{content_id}` - if the passed `content_id` in the path does not exist or link to an existing piece of content, the `GET` results in a 404. * The URL `channels/123/content/456` results in 404 if the channel or the content doesn't exist, or if the content exists but is not associated to the channel. Additionally, requests for contextually private resources may return 404 as a way to avoid revealing the presence of the resource. ### 409 **Conflict** Returned by some endpoints when attempting to use or update an identifier that is already taken by another record in that collection. ### 429 **Too Many Requests** Returned when the rate limit is exceeded. The rate limit is 1,000 requests per minute, per program. A delay and a retry is recommended. ## Server Error Codes Error codes in the range 500 - 599 indicate an error on the server. Clients should retry their request again later, or contact support for assistance. | Status Code | Description | | --- | --- | | 500 | Internal server error | | 504 | Request timeout | ## Ask AI Assistant Ask our AI assistant to help troubleshoot issues: 1. Select the search bar. 2. Type in your question, copy any code, and give it the error code. You may want to also give it the endpoint. The more details it has, the better chance it has of troubleshooting. 3. Select Search with AI, or Ask AI Assistant. 4. This opens up your AI assistant chat bot. It may ask for more details if required. Screenshot 2025-10-13 at 14.20.01.png