The Texas State Reporting Ed-Fi pages are only for pilot districts in Texas that are testing the TSDS Ed-Fi processes. All other districts should refer to Texas State Reporting documentation.
The information below is based on Ed-Fi ODS-API Error Responses
Terminology
The following terminology is associated with APIs and may appear in error message generated by the Ed-Fi IODS.
- Array: A set of the same Data Elements with different values, such as a bell schedule.
- Association: Two Entities that are related via one or more shared keys.
- Data Element: A specific piece of information, such as a student's first name.
- Descriptor: A Data Element that has a specific set of codes, such as GradeLevel.
- Domain: A group of related Entities.
- Endpoint: The URI that indicates the path to a specific Data Element.
- Entity: A group of related Data Elements.
- Namespace: The portion of the URI that indicates the governing entity (ed-fi.org) and the Descriptor.
- Natural key: A column that uniquely identifies a record and contains content that is meaningful to the users, such as Student Last Name, as opposed to a key that has less meaningful data such as an ID.
- Payload: The data that is sent in an API request or received in an API response.
- Sync/Synchronization: The process of comparing local Aeries data to data that exists on the Ed-Fi IODS server. Data that has been added, changed, or deleted in Aeries is updated on the Ed-Fi IODS server.
- Attribute/Property: The Data Elements and their Values for a particular Entity. For example, the attributes for the AssessmentResults entity are Assessment Date, Score Accommodations, etc.
- URI (Uniform Resource Identifier): Similar to a URL but identifies any type of resource, not just one on the internet.
- Value:
- String: User-entered value with a specified maximum number of characters
- Code Set: The list of defined values allowed for a particular Descriptor. If local codes are used they must be mapped to state-defined codes.
- Date: A value formatted as a date
- Boolean: Yes/No indicators
NOTE: The \r, \n, and \t characters in the messages are "escape sequence" codes that are automatically generated by the Ed-Fi IODS/API. The \r represents a carriage return, \n represents a newline (linefeed), and \t represents tab. These characters can be ignored.
400 BAD REQUEST Errors ↑
| TSDS Error | Recommendation |
| POST request contains an id value | Remove the id value from the payload for POST request. NOTE: The id value is required for a PUT request. |
| "message": "Resource identifiers cannot be assigned by the client." | |
| Missing a property | Verify that all required data is being transmitted. |
"message": "Validation of 'Endpoint' failed.\r\n\tProperty is required.\n" | |
| Missing two properties | |
"message": "Validation of 'Endpoint' failed.\r\n\tProperty1 is required.\n\tProperty2 is required.\n" | |
| Property exists but is empty or set to null | |
"message": "Validation of 'Endpoint' failed.\r\n\tProperty is required.\n" | |
| String length is too long | Shorten the string. |
| "message": "Validation of 'Endpoint' failed.\r\n\tThe field Property must be a string with a maximum length of NN.\n" | |
| Student does not exist in StudentSchoolAssociations | A 400 Error in this situation is rare. Typically a 409 error is generated in this situation. Ensure that the student record was created correctly. Ensure no errors exist in the student data. Ensure that the data is submitted following the required Domain Dependency Order (see below). |
"message": "Validation of 'StudentSchoolAssociation' failed.\r\n\tStudent reference could not be resolved.\n" or "message": "Validation of 'StudentSchoolAssociation' failed. Student reference could not be resolved." | |
| Unable to delete an item due to upstream dependency | Delete data following the Domain Dependency Order (see below) in reverse order (delete children first). |
"message": "The resource (or a subordinate entity of the resource) cannot be deleted because it is a dependency of the 'DataElement' value of the 'EntityName' entity."} | |
"message": "The resource (or a subordinate entity of the resource) cannot be deleted because it is a dependency of the 'DataElement' value of the 'StudentUSI' entity."} | Verify whether a Student Unique ID changed. A Student Unique ID cannot be updated using a PUT request. The student record must be deleted and resubmitted when there is a change to the Student Unique ID. |
| Descriptor does not exist or is invalid, or base URI is wrong | Verify the code mapping for the Descriptor, and whether the value is in the code or entered by the user in Aeries. Verify that the base URI is ed-fi.org. |
| "message": "Unable to resolve value 'uri://ed-fi.org/Endpointr#CodeValue' to an existing 'DataElementDescriptor' resource." | |
Invalid POST or PUT request (non-compliant JSON code) | Verify that multiple trailing commas do not exist. |
"message": "The request is invalid.", "modelState": { "request.EntityReference.DataElement": [ "Invalid property identifier character: ,. Path 'EntityReference.DataElement', line N, position NN." ], "request.EntityReference.DataElement.EntityReference": [ "Invalid property identifier character: ,. Path 'EntityReference.DataElement', line N, position NN." | |
"message": "The request is invalid.", "modelState": { "request.EntityReference": [ "Unexpected end when deserializing object. Path 'EntityReference', line N, position N." | Verify that closing curly braces exist. |
| Integer absolute value is too large | "Int32" indicates the storage capacity of integers. The Ed-Fi API only supports Int32. If Aeries supports Int64, create a new Int32 value alongside the existing Int64 value, for transmission to the Ed-Fi API. |
"message": "The request is invalid.", "modelState": { "request.DataElementReference.DataElementID": [ "JSON integer XXXXXXXXXX is too large or small for an Int32. Path 'DataElementReference.DataElementID', line N, position NN." ] | |
| String length exceeds maximum | Ensure that value length meets string requirements, per Swagger UI documentation and Ed-Fi core data model documentation. |
| "message": "Validation of 'DataElement' failed.\r\n\tThe field DataElement must be a string with a maximum length of NN.\n" | |
| Object contains no properties | Verify that all required properties are transmitted. |
| "message": "Value for resource's identifier property 'DataElement' is required." | |
| Empty body | Verify that the POST or PUT request contains a body. |
"message": "A non-empty request body is required." | |
| Wrong character encoding | Verify that charset=utf-8 in the POST or POST request. |
| "message": "Unexpected character encountered while parsing value: character. Path '', line N, position N." | |
| Potentially dangerous value | Ensure that no Aeries user is attempting to perform a malicious injection attack. Encode the < character as <. |
"message": "Validation of 'DataElement' failed.\r\n\tThe field DataElement must be a string with a maximum length of NN.\n\tDataElement contains a potentially dangerous value.\n" | |
| Leading or trailing space in string | Remove spaces from the beginning or end of the string. |
"message": "Validation of 'DataElement' failed.\r\n\tDataElement property is part of the primary key and therefore its value cannot contain leading or trailing whitespace.\n" | |
| Required array is empty | Verify that the array contains at least one Data Element. |
| "message": "Validation of 'Array' failed.\r\n\tArrayDataElement requires at least one object in the collection.\n" | |
Item in an array is missing a required property | Verify that the data element for the particular array ([N]) contains valid data. |
| "message": "Validation of 'Entity' failed.\n\tValidation of 'Array' failed.\n\t\tArray[N]: DataElement is required.\n" | |
| Inconsistent keys (key unification error) | Verify that valid data element data is being transmitted for both entities. |
"message": "Validation of 'EntityPost' failed.\n\tSupplied values for unified key property 'DataElement' on 'Entity' are not consistent: EntityReference.DataElement = XXXXXXXX, EntityReference.DataElement = XXXXXXXX\n" | |
Invalid limit count for GET requests | Verify the max count of records that can be returned for a GET request. The default is 500. |
"message": "Limit must be omitted or set to a value between 1 and max value defined in configuration file (defaultPageSizeLimit)." | |
| Entity cannot find the referenced value | The API cannot find the referenced Student entity with the matching UID. Verify that the StudentSchoolAssociation entity with the matching UID has been published Verify that the StudentSchoolAssociation entity with the matching UID has not been flagged in the Level 1.5 filters Verify there are no level 1 errors in the StudentSchoolAssociation entity for the UID |
400-Bad Request “….reference could not be resolved…” "message": “Validation of ‘StudentSchoolAssociation’ failed. Student reference could not be resolved.” |
401 UNAUTHORIZED Errors ↑
| TSDS Error | Recommendation |
| Missing, invalid, or expired content | For security reasons the application does not provide detailed information about reason for unauthorized errors. Possible reasons:
|
| RESPONSE: HTTP/1.1 401 Unauthorized Content-Type: application/json; charset=utf-8 |
403 FORBIDDEN Errors ↑
| TSDS Error | Recommendation |
| Missing namespace for descriptor | Verify that the namespace is populated. |
| "message": "Access to the resource item could not be authorized because the Namespace of the resource is empty." | |
| Invalid namespace for descriptor | Verify that the client credentials are configured for access to appropriate namespaces. |
"message": "Access to the resource item could not be authorized based on the caller's NamespacePrefix claims: 'uri://ed-fi.org', 'uri://example1.org', 'uri://example2.org'." | |
Student/Parent/Staff relationship does not exist | Verify that a valid StudentSchoolAssociation , studentParentAssociation, or staffSchoolAssociation record is created only after creating the corresponding Student, Parent, or Staff objects. Verify that the association was created. |
"message": "Authorization denied. No relationships have been established between the caller's education organization id claims (NNNNNN, NNNNNNNN) and the resource item's 'Parent/Student/StaffUniqueID' value." | |
Invalid credentials for the school or education organization | Verify that the client credentials are configured for access to that SchoolId. Verify that the schoolID exists. Verify that the correct SchoolID is being transmitted. |
"message": "Authorization denied. No relationships have been established between the caller's education organization id claims (NNNNNN, NNNNNNNN) and the resource item's 'SchoolId' value." or "message": "Authorization denied. No relationships have been established between the caller's education organization id claim (2) and one or more of the following properties of the resource item: 'EducationOrganizationId', 'StudentUniqueId'." | |
| Not authorized for access to the school | Verify that the client was given explicit access to the specific school or education organization. Verify that the schoolID exists. Verify that the schoolID belongs to a school rather than a non-school type of education organization. Verify that the correct SchoolID is being transmitted. |
message": "Authorization denied. Access to the requested 'SchoolId' was denied." | |
| Invalid namespace prefix | Verify that the correct namespace is used. |
| "message": "Access to the resource item could not be authorized based on the caller's NamespacePrefix claims: 'uri://example.com'." | |
| Requested action is not permitted | Do not perform the action. Or increase the latitude of the credentials, as defined in the claim set. |
| "message": "Access to the resource could not be authorized for the requested action 'http://ed-fi.org/odsapi/actions/update'." | |
| Missing claim | Do not perform the action. Or replace the credentials with a new client ID/secret pair that uses a different claim set. |
"message": "Access to the resource could not be authorized. Are you missing a claim? This resource can be authorized by the following claims:\r\n http://ed-fi.org/ods/identity/claims/example1\n http://ed-fi.org/ods/identity/claims/example2\n http://ed-fi.org/ods/identity/claims/example3\r\nThe API client has been assigned the 'SIS Vendor' claim set with the following resource claims:\r\n http://ed-fi.org/ods/identity/claims/Example1\n http://ed-fi.org/ods/identity/claims/Example2\n http://ed-fi.org/ods/identity/claims/Example3\n" |
404 NOT FOUND Errors ↑
| TSDS Error | Recommendation |
| Resource name typo | Verify that the exact URL and path are accurate. If the URL is accurate, determine whether the hosting provider is running in an instance mode that introduces an additional segment to the URL such as a school year or a district name. |
| RESPONSE: HTTP/1.1 404 Not Found | |
| ID does not exist (PUT and DELETE requets) | Use a GET request with a natural key to look up the correct ID. |
| RESPONSE: HTTP/1.1 404 Not Found | |
| Space at the end of the URL | Verify that there is no extra space at the end of the URL. If spaces in the URL are encoded (e.g., '%20') verify that the encoded space is removed from the end of the URL. |
| RESPONSE: HTTP/1.1 404 Not Found |
405 METHOD NOT ALLOWED Errors ↑
| TSDS Error | Recommendation |
| PUT request with ID | Versions 7.0 and later require the ID in the PUT request. For versions 7.0 and later append the ID value. For earlier versions, remove the ID value. Locate the ID value in the location header response from a POST or GET request. NOTE: ODS/API versions prior to 7.0 erroneously blocked PUT requests that contained an ID value. Versions 7.0 and later require the ID in the PUT request. Certain 7.x versions allow PUT requests without the ID. |
| RESPONSE: HTTP/1.1 405 Method Not Allowed |
409 CONFLICT Errors ↑
| TSDS Error | Recommendation |
| Duplicate values for descriptor code value and namespace | This error is uncommon. The ODS/API performs an "upsert" when it receives a POST request. If the natural key already exists on a record, the record is updated to match the new request body. Do not transmit a the value in the payload. Send to application development team for resolution. |
| "message": "The values unknown supplied for properties 'codeValue', 'namespace' of entity 'descriptor' are not unique." or "message": "The value unknown supplied for property 'unknown' of entity 'descriptor' is not unique." | |
| ID mismatch causing accidental attempt to change natural key of an object to values that already exist on another object | Avoid using natural key values for a code value and namespace in PUT requests. Verify that the ID value in the URL and payload are valid for the Descriptor. |
| "message": "The values unknown supplied for properties 'codeValue', 'namespace' of entity 'descriptor' are not unique." | |
| Missing Student or Staff | Verify that the student or staff record is created before the association record is created. |
"message": "Access to the resource item could not be authorized because the 'Staff' was not found." or "message": "Access to the resource item could not be authorized because the 'Student' was not found." | |
| Invalid reference | Verify that key values in both references match. Verify that the user credentials allow access to a particular school year. Ensure that the data is submitted following the required Domain Dependency Order (see below). Ensure that the entity was created correctly. |
| "message": "The value supplied for the related 'schoolYearType' resource does not exist." or "message": "The value supplied for the related 'Entity' resource does not exist." | |
Attempting to delete a resource that has dependencies | Delete data following the Domain Dependency Order (see below) in reverse order (delete children first). Verify all dependencies for the data element, not just the dependency referenced in the error message. |
"message": "The resource (or a subordinate entity of the resource) cannot be deleted because it is a dependency of the 'DataElement' value of the 'EntityAssociation' entity." |
415 Unsupported Media Type ↑
| TSDS Error | Recommendation |
| The content-type header is missing or is not "application/json" | Verify that the header includes Content-Type: application/json. The charset is optional and assumed to be UTF-8 when omitted. |
| RESPONSE: HTTP/1.1 415 Unsupported Media Type |
500 Internal Server Error ↑
| TSDS Error | Recommendation |
| RESPONSE: HTTP/1.1 500 Internal Server Error | This error is a "catch all" for all possible server errors. Verify that the header includes Content-Type: application/json. |
Other Errors ↑
| Error | Recommendation |
| A natural key conflict occurred when attempting to update a new resource with a duplicate key. | This may occur if multiple Aeries codes are mapped to the same descriptor in Ed-Fi (i.e., multiple resources with the same key in the same file). Only one resource is updated. Verify the code mapping for all elements of this entity. |
| Authorization denied. The claim does not have any established relationships with the requested resource. | |
The request included an entity which couldn’t be found in the ODS | Verify that all dependencies for this request were successfully sent to the ODS. For example, for StudentParentAssociation verify that both the Student and the Parent referenced in the request exist in the ODS. . |
message: Access to the resource item could not be authorized because the 'DataElementName} of the resource is empty. | |
| Student was not found in the ODS | The request included a student which couldn’t be found in the ODS. For example, for StudentEducationOrganization the student must first exist in the ODS for that school from the StudentSchoolCombinations entity. |
message: Access to the resource item could not be authorized because the 'Student' was not found. | |
| Duplicate records | Verify that there are not overlapping begin and end dates or duplicate records in Aeries for that set of data. |
Exception was thrown while creating ‘{EntityName}’ … The # item of the ‘{EntitySetName}’ collection is a duplicate | |
| Aeries received no response from either the API endpoint or OAuth endpoint | Verify the configuration and test the base URL of the the URLs in the browser. |
Message: Unable to connect to the remote server | |
| Code is not mapped to a valid Ed-Fi or TEA descriptor code | Verify that the Code Set specified includes all of your Aeries codes and they are mapped to a valid Ed-Fi Namespace & Code. Note: The value of 0 for several codes sets was removed and the Ed-Fi Namespace & code should be left blank as the data element will no longer be sent instead of sending a 0 value to indicate this element does not apply. |
Message: Validation of ‘{EntityName}’ failed. Unable to resolve value ‘{DescriptorValue}’ to an existing ‘{DescriptorCodeSetName}’ resource. | |
| The entity is missing a required mapping | Verify that the code sets for the entity include all of your Aeries codes and they are mapped to a valid Ed-Fi Namespace & Code. The StaffServiceSet (Tx) is hard coded and not a mapping code set so it is due to another missing codes set required such as Population Served. |
Entity.DataElementName requires at least one object in the collection. | |
| Overlapping records | There are overlapping Parental Permission Records or Authorizations without a status or end date. Delete one of the overlapping parental permission records from the Authorizations or Language Assessment page or edit the dates so they are no longer overlapping. Enter all Authorization Status dates (AUT.SDT) |
Exception was thrown while creating StudentLanguageInstructionProgramAssociation, Exception has been thrown by the target of an invocation., Exception has been thrown by the target of an invocation., Error calling PostStudentLanguageInstructionProgramAssociation: { "message": "An unexpected error occurred on the server." } | |
| Entity comes from a prior year database | Two years of data in the AeriesNetConnections file is required. |
Prior Year Leaver Exception was thrown while upserting PriorYearLeaver, DbConnectionString, DbConnectionString |
Domain Dependency Order
- Education Organization Domain
- Student Identification and Demographics Domain
- School Calendar Domain
- Staff Domain
- Enrollment Domain
- Restraint Event Domain
- Finance Domain
- Discipline Domain
- Student Application Domain
- Teaching and Learning Domain
- Student Academic Record Domain
- Alternative and Supplemental Services Domain
- Prior Year Leaver Domain
- Assessment Domain
- Student Cohort Domain